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Introduction to Xlib 



The X Window System is a network-transparent window system that was 
designed at MIT. It runs under 4.3BSD UNIX, ULTRIX-32, many other UNIX 
variants, VAX/VMS, MS/DOS, as well as several other operating systems. 

AT&T's XwiN™ Release 3.0 product is based on the MIT X Window System 
X11R3. It is streams based, includes performance enhancements, and runs on 
UNIX System V Release 3.2 and SVR4.0 

XwiN display servers run on computers with either monochrome or color bit- 
map display hardware. The server distributes user input to and accepts output 
requests from various client progranns located either on the same machine or 
elsewhere in the network. Xlib is a C subroutine library that application pro- 
grams (clients) use to interface with the window system by means of a stream 
connection. Although a client usually runs on the same machine as the XwiN 
server it is talking to, this need not be the case. 

Xlib - C Language X Interface is a reference guide to the low-level C language 
interface to the X System protocol. It is neither a tutorial nor a user's guide to 
programming the XwiN System. Rather, it provides a detailed description of 
each function in the library as well as a discussion of the related background 
information. Xlib - C Language X Interface assumes a basic understanding of a 
graphics window system and of the C programming language. Other higher- 
level abstractions (for example, those provided by the toolkits for X) are built on 
top of the Xlib library. For further information about these higher-level 
libraries, see the appropriate toolkit documentation. The X Protocol provides the 
definitive word on the behavior of X. Although additional information appears 
here, the protocol document is the ruling document. 

To provide an introduction to X programming, this chapter discusses: 

■ Overview of the XwiN System 

■ Errors 

■ Naming and argument conventions 

■ Programming considerations 

■ Conventions used in this document 
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Overview of the XWIN System 



Some of the ternis used in this book are unique to the XwiN System, and other 
terms that are common to other window systems have different meanings in 
XwiN. You may find it helpful to refer to the glossary, which is located at the 
end of the book. 

All the windows in an XwiN server are arranged in strict hierarchies. At the top 
of the hierarchy is the root window, which covers the display screen. Each root 
window is partially or completely covered by child windows. All windows, 
except for root windows, have parents. There is usually at least one window for 
each application program. Child windows may in turn have their own children. 
In this way, an application program can create an arbitrarily deep tree. The 
XwiN system provides graphics, text, and raster operations for windows. 

A child window can be larger than its parent. That is, part or all of the child 
window can extend beyond the boundaries of the parent, but all output to a 
window is clipped by its parent. If several children of a window have overlap- 
ping locations, one of the children is considered to be on top of or raised over 
the others thus obscuring them. Output to areas covered by other windows is 
suppressed by the window system unless the window has backing store. If a 
window is obscured by a second window, the second window obscures only 
those ancestors of the second window, which are also ancestors of the first win- 
dow. 

A window has a border zero or more pixels in width, which can be any pattern 
(pixmap) or solid color you like. A window usually but not always has a back- 
ground pattern, which will be repainted by the window system when 
uncovered. Each window has its own coordinate system. Child windows 
obscure their parents unless the child windows (of the same depth) have no 
background, and graphic operations in the parent window usually are clipped 
by the children. 

The XwiN server does not guarantee to preserve the contents of windows. When 
part or all of a window is hidden and then brought back onto the screen, its 
contents may be lost. The server then sends the client program an EiKpose event 
to notify it that part or all of the window needs to be repainted. Programs must 
be prepared to regenerate the contents of windows on demand. 

The XwiN server also provides off-screen storage of graphics objects, called pix- 
maps. Single plane (depth 1) pixmaps are sometimes referred to as bitmaps. 
Pixmaps can be used in most graphics functions interchangeably with windows 
and are used in various graphics operations to define patterns or tiles. Win- 
dows and pixmaps together are referred to as drawables. 
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Overview of the Xwin System 



Most of the functions in Xlib just add requests to an output buffer. These 
requests later execute asynchronously on the XwiN server. Functions that return 
values of information stored in the server do not return (that is, they block) 
until an explicit reply is received or an error occurs. You can provide an error 
handler, which will be called when the error is reported. 

If a client does not want a request to execute asynchronously, it can follow the 
request with a call to XSync, which blocks until all previously buffered asyn- 
chronous events have been sent and acted on. As an important side effect, the 
output buffer in Xlib is always flushed by a call to any function that returns a 
value from the server or waits for input. 

Many Xlib functions will return an integer resource ID, which allows you to 
refer to objects stored on the XwiN server. These can be of type Window, Font, 
Pixmap, Colonnap, Cursor, and GContext, as defined in the file < Xll/X.h >. 

These resources are created by requests and are destroyed (or freed) by requests 
or when connections are closed. Most of these resources are potentially sharable 
between applications, and in fact, windows are manipulated explicitly by win- 
dow manager programs. Fonts are loaded and unloaded as needed and are 
shared by multiple clients. Fonts are often cached in the server. Xlib provides 
no support for sharing graphics contexts between applications. 

Client progran\s are informed of events. Events may either be side effects of a 
request (for example, restacking windows generates Expose events) or com- 
pletely asynchronous (for example, from the keyboard). A client program asks 
to be informed of events. Because other applications can send events to your 
application, programs must be prepared to handle (or ignore) events of all 
types. 

Input events (for example, a key pressed or the pointer moved) arrive asynchro- 
nously from the server and are queued until they are requested by an explicit 
call (for example, XNext Event or XWindowEvent). In addition, some library 
functions (for example, XRaiseWindow) generate Expose and Conf igureRe- 
quest events. These events also arrive asynchronously, but the client may wish 
to explicitly wait for them by calling XSync after calling a function that can 
cause the server to generate events. 
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Overview of the Xwin System 



The <> has the meaning defined by the # include statement of the C com- 
NOT£ piier and is a file relative to a well-known directory. This is /usr/X/include 
on Xwin systems. 
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Errors 



Some functions return Status, an integer error indication. If the function fails, 
it returns a zero. If the function returns a status of zero, it has not updated the 
return arguments. Because C does not provide multiple return values, many 
functions must return their results by writing into client-passed storage. 

By default, errors are handled either by a standard library function or by one 
that you provide. Functions that return pointers to strings return NULL 
pointers if the string does not exist 

The XwiN server reports protocol errors at the time that it detects them. If more 
than one error could be generated for a given request, the server can report any 
of them. 

Because Xlib usually does not transmit requests to the server immediately (that 
is, it buffers them), errors can be reported much later than they actually occur. 
For debugging purposes, however, Xlib provides a mechanism for forcing syn- 
chronous behavior (see "Enabling or Disabling Synchronization" in Chapter 8). 
When s3mchronization is enabled, errors are reported as they are generated. 

When Xlib detects an error, it calls an error handler, which your program can 
provide. If you do not provide an error handler, the error is printed, and your 
program terminates. 
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Naming and Argument Conventions within Xiib 



Xlib follows a number of conventions for the naming and syntax of the func- 
tions. Given that you remember what information the function requires, these 
conventions are intended to make the syntax of the functions more predictable. 

The major naming conventions are: 

■ To differentiate the XwiN symbols from the other symbols, the library uses 
mixed case for external symbols. It leaves lowercase for variables and all 
uppercase for user macros, as per existing convention. 

■ All Xlib functions begin with a capital X 

■ The beginnings of all function names and symbols are capitalized. 

■ All user-visible data structures begin with a capital X. More generally, 
anything that a user might dereference begins with a capital X. 

■ Macros and other symbols do not begin with a capital X. To distinguish 
them from all user symbols, each word in the macro is capitalized. 

■ All elements or variables in a data structure are in lowercase. Compound 
words, where needed, are constructed with underscores O. 

■ The display argument, where used, is always first in the argument list. 

■ All resource objects, where used, occur at the beginning of the argument 
list immediately after the display argument. 

■ When a graphics context is present together with another type of 
resource (most commonly, a drawable), the graphics context occurs in the 
argument list after the ottter resource. Drawables outrank all other 
resources. 

■ Source arguments always precede the destination arguments in the argu- 
ment list. 

■ The X argument always precedes the y argument in the argument list. 

■ The width argument always precedes the height argument in the argu- 
ment list. 

■ Where the x, y, width, and height arguments are used together, the x and 
y arguments always precede the width and height arguments. 
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■ Where a mask is accompanied with a structure, the mask always precedes 
the pointer to the structure in the argument list 
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Programming Considerations 



The major programming considerations are: 

■ Keyboards are the greatest variable between different manufacturers' 
workstations. If you want your program to be portable, you should be 
particularly conservative here. 

■ Many display systems have limited amounts of off-screen memory. If you 
can, you should minimize use of pixmap>s and backing store. 

■ The user should have control of the screen real estate. Therefore, you 
should write your applications to react to window management rather 
than presume control of the entire screen. What you do inside of your 
top-level window, however, is up to your application. For further infor- 
mation, see Chapter 9. 

■ Coordinates and sizes in the XwiN System are actually 16-bit quantities. 
They usually are declared as an "inf ' in the interface (int is 16 bits on 
some machines). Values larger than 16 bits are truncated silently. Sizes 
(width and height) are unsigned quantities. This decision was taken to 
nunimize the bandwidth required for a given level of performance. 
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Conventions Used in Xlib - C Language X 
Interface 

This document uses the following conventions: 

■ Global symbols in Xlib - C Language X Interface are printed in this spe- 
cial font. These can be either function names, symbols defined in 
include files, or structure names. Arguments are printed in italics. 

■ Each function is introduced by a general discussion that distinguishes it 
from other functions. The function declaration itself follows, and each 
argument is specifically explained. General discussion of the function, if 
any is required, follows the arguments. Where applicable, the last para- 
graph of the explanation lists the (>ossible Xlib error codes that the func- 
tion can generate. For a complete discussion of the Xlib error codes, see 
"Using the Default Error Handlers" in Chapter 8. 

■ To eliminate any ambiguity between those arguments that you pass and 
those that a function returns to you, the explanations for all arguments 
that you pass start with the word specifies or, in the case of multiple argu- 
ments, the word specify. The explanations for all arguments that are 
returned to you start with the word returns or, in the case of multiple 
arguments, the word return. The explanations for all arguments that you 
can pass and are returned start with the words specifies and returns. 

m Any pointer to a structure that is used to return a value is designated as 
such by the ^return suffix as part of its name. All other pointers passed to 
these functions are used for reading only. A few arguments use pointers 
to structures that are used for both input and output and are indicated by 
using the jnj)ut suffix. 

■ Xlib defines the Boolean values of True and False. 
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Introduction 



Before your program can use a display, you must establish a connection to the 
XwiN server. Once you have established a connection, you then can use the Xlib 
macros and functions discussed in this chapter to return information about the 
display. This chapter discusses how to: 

■ Open (connect to) the display 

■ Obtain information about the display, image format, and screen 

■ Free client-created data 

■ Close (disconnect from) a display 

The chapter concludes with a general discussion of what occurs when the con- 
nection to the XwiN server is closed. 
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Opening the Display 



To open a connection to the XwiN server that controls a display, use XOpen- 
Display. 

Display *XppenDisplay (display jiame) 
char display jume; 

display jume Specifies the hardware display name, which determines the 

display and communications domain to be used. On a UNIX- 
based system, if the display_name is NULL, it defaults to the 
value of the DISPLAY environment variable. 

On UNIX-based systems, the display name or DISPLAY environment variable is 
a string in the format: 

hostmme:nvniber,scremjiimi^ 

hostname Specifies the name of the host machine on which the display is 
physically attached. You follow the hostname with either a sin- 
gle colon (:) or a double colon (::). 

number Specifies the number of the display server on that host machine. 

You may optionally follow this display number with a period 
(.). A single CPU can have more than one display. Multiple 
displays are usually numbered starting with zero. 

screenjtumber Specifies the screen to be used on that server. The 

screen_number sets an internal variable that can be accessed by 
using the DefaultScreen macro or the XDefaultScreen func- 
tion if you are using languages other than C (see "Display Mac- 
ros" in Chapter 2), 

For example, the following would specify screen 2 of display 0 on the machine 
named mit-athena: 

]iiit-athona:0.2 

The XppenDisplay function returns a Display structure that serves as the con- 
nection to the XwiN server and that contains all the information about that XwiN 
server. XppenDisplay connects your application to the XwiN server through 
TCP, UNIX domain, or StarLan (SVR3.2 only) communications protocols. If the 
hostame is a host machine name and a single colon (:) separates the hostname 
and display nuniber XppenDisplay connects using TCP streams. If the 
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hostname is unix and a single colon (:) separates it from the display number, 
XOpenDisplay connects using UNIX domain IPC streams. If the hostname is 
not specified, Xlib uses whatever it believes is the fastest transport. A single 
XwiN server can support any or all of these transport mechanisms simultane- 
ously. A particular Xlib implementation can support many more of these tran- 
sport mechanisms. 

If successful, XOpenDisplay returns a pointer to a Display structure, which is 
defined in < Xll/Xlib.h >. If XOpenDisplay does not succeed, it returns 
NULL. After a successful call to XOpenDisplay, all of the screens in the display 
can be used by the client. The screen number specified in the display_name 
argument is retumed by the DefaultScreen macro (or the XDefaultScreen 
function). You can access elements of the Display and Screen structures only 
by using the information macros or functions. For infonnation about using 
macros and functions to obtain information from the Display structure, see 
"Display Macros" in Chapter 2. 

XwiN servers may implement various types of access control mechanisms (see 
"Controlling Host Access" in Chapter 7). 
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Obtaining Information about the Display, 
image Formats, or Screens 



The Xlib library provides a number of useful macros and corresponding func- 
tions that return data from the Display structure. The macros are used for C 
programming, and their corresponding function equivalents are for other 
language bindings. This section discusses the: 

■ Display macros 

■ Image format macros 

■ Screen macros 



All other members of the Display structure (that is, those for which no macros 
are defined) are private to Xlib and must not be used. Applications must never 
directly modify or inspect these private members of the Display structure. 



«OTE 



The XDisplayWidth, XDisplaylfeight, XDisplayCells, XDisplayPlanes, 
XDisplayWidthbfi, and XDisplayHeightMi functions in tlie next sections 
are misnamed. Tliese functions really should be named Screenwhatever and 
XScreenu^/io^^r, not D\sp\aywhatever or XD\sp\aywhatever. Our apologies 
for the resulting confusion. 



Display Macros 

Applications should not directly modify any part of the Display and Screen 
structures. The members should be considered read-only, although they may 
change as the result of other operations on the display. 

The following lists the C language macros, their corresponding function 
equivalents that are for other language bindings, and what data they both can 
return. 

AllPlanesO 

unsigned long X2U.IP lanes () 

Both return a value with all bits set to 1 suitable for use in a plane argument to 
a procedure. 
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Both BlackPixel and WhitePixel can be used in implementing a monochrome 
application. These pixel values are for permanently allocated entries in the 
default colormap. The actual RGB (red, green, and blue) values are settable on 
some screens and, in any case, may not actually be black or white. The names 
are intended to convey the expected relative intensity of the colors. 

BladkBixBH display, screen jtumher) 

unsigned long XBlackPixel(<2is;72ay, scremjiumher) 
EMsplay ^display; 
int screenjiuniber', 

Both return the black pixel value for the specified screen. 

yntdt^ixbl {display, screenjmmber) 

unsigned long XWhitePlxel(<2isp2ay, screenjiumber) 
CHsplay ^display; 
int screenjiuniber; 

Both return the white pixel value for the specified screen. 

ConnectionMuinber ( display) 

int XConnectionNumber(iisplay) 
EHsplay *display; 

Both return a connection number for the specified display. On a UNIX-based 
systeni, this is the file descriptor of the connection. 

DefaultColonoapC display, screenjiumber) 

Colormap XDefaultCol<»:map((2isplay, screenjiumber) 
Display *display; 
int screenjiumber; 

Both return the default colormap ID for allocation on the specified screen. Most 
routine allocations of color should be made out of this colormap. 
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DefaultD6pth(itsfy2ay, screenjtumher) 

int XDefaultDepth(<ltsfy2ay, screatjtumher) 
Display *display; 
int screenjiumher; 

Both return the depth (number of planes) of the default root window for the 
specified screen. Other depths may also be supported on this screen (see 
XMatchVisuallnfo). 

DefaultGC {display, screenjiuniber) 

GC XDefaultGCCiispZoy, sctemjiuniber) 
Display ^display; 
int scremjivmher; 

Both return the default graphics context for the root window of the specified 
screen. This GC is created for the convenience of simple applications and con- 
tains the default GC components with the foreground and background pixel 
values initialized to the black and white pixels for the screen, respectively. You 
can modify its contents freely because it is not used in any Xlib function. This 
GC should never be freed. 

Defai2lt:RootWiiidow (display) 

Window XDefai]ltRootWindow(itsp2ay) 
Display "^display; 

Both return the root window for the default screen. 

Def aultSksre«nO£Di^lay ( display) 

Screen ^XDefaiiltScieenQfDisplayCi/is^/ay) 
Display ^display; 

Both return a pointer to the default screen. 

ScreenOfDiflplay (display, screenjtumher) 

Screen *XScreenQfDisplay(i2ispi^y, screenjiumher) 
Display * display; 
int screenjiumher; 
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Both return a pointer to the indicated screen. 

DefaultSorean (iisp/oy) 

int XDefaultScreen((fisp/ay) 
Display ^display; 

Both return the default screen number referenced by the XOpenDisplay func- 
tion. This macro or function should be used to retrieve the screen number in 
applications that will use only a single screen. 

DefaultVisuaK (display, screenjtumber) 

Visual *XDefaultVisual((2isp2^, screenjtuniber) 
Display *display; 
int screenjtumber; 

Both return the default visual type for the specified screen. For further informa- 
tion about visual types, see "Visual Types** in Chapter 3. 

DiaplaYC^llB {display, saremjttmiber) 

int XDisplayCells(itspliiy, screenjtumher) 
Display ^display; 
int screenjtumber; 

Both return the number of entries in the default colormap. 

DisplayP lanes (itsp/oy, screenjiumber) 

int XDisplayP]anes(itsp/ay, screenjtumber) 
Display * display; 
int screenjtuniber; 

Both return the depth of the root window of the specified screen. For an expla- 
nation of depth, see the glossary. 

DiflplayString ( display) 

char '^XDisplayStringCtfisplay) 
Display ^display; 
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Both return the string that was passed to XOpenDisplay when the current 
display was opened. On UNIX-based systems, if the passed string was NULL, 
these return the value of the DISPLAY environment variable when the current 
display was opened. 

These are useful to applications that invoke the fork system call and want to 
open a new connection to the same display from the child process as well as for 
printing error messages. 

LaatKhownRaquestProceBsed ( display) 

tmsigned long XLa8tKnownRequestProcessed(iis;92ay) 
Display *displaif; 

Both extract the full serial number of the last request known by Xlib to have 
been processed by the XwiN server. Xlib automatically sets this number when 
replies, events, and errors are received. 

NextRaqueat (display) 

unsigned long XNextRequest(iiisplay) 
Display *display; 

Both extract the full serial number that is to be used for the next request. Serial 
numbers are maintained separately for each display connection. 

Protoool\%raion (display) 

int XProtocolVersion(iis;iZay) 
Display ^display; 

Both return the major version number (11) of the X protocol associated with the 
connected display. 

ProtoooIReviaion ( dispiay) 

int XProtocolRevision(iis^2ay) 
Display ^display; 

Both return the minor protocol revision number of the XwiN server. 

QljBngth( display) 

int XQheng^(display) 
Display ^display; 
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Both return the length of the event queue for the connected display. Note that 
there may be more events that have not been read into the queue yet (see 
XEventsQueued). 

RootWiiidow (f^isp/oy, screen number) 

Window XRootWindow((jisp2ay, screenjtumher) 
Display *dispUiy; 
int screenjiumber; 

Both return the root window. These are useful with functions that need a draw- 
able of a particular screen and for creating top-level windows. 

ScraonCount {display) 

int XScreenCount(({is;7l<iy) 
Display *disp1ay; 

Both return the number of available screens. 

ServexVendor ( display) 

char *XServer Vendor ((fisptey) 
Display *displaif; 

Both return a pointer to a null-terminated string that provides some 
identification of the owner of the XWIN server implementation. 

VendoxReleaae ( display) 

int XWeRdoiReieaseidisplay) 
Display *display; 

Both return a number related to a vendor's release of the XwiN server. 
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Image Format Macros 

Applications are required to present data to the XwiN server in a format that the 
server demands. To help simplify applications, most of the work required to 
convert the data is provided by Xlib (see "Transferring Images Between Qient 
and Server" in Chapter 6, and "Manipulating Images" in Chapter 10). 

The following lists the C language macros, their corresponding function 
equivalents that are for other language bindings, and what data they both 
return for the specified server and screen. These are often used by toolkits as 
well as by simple applications. 

ImageByteOrder (display) 

int XImageByteQrder((fts;7%) 
Display ^display; 

Both specify the required byte order for images for each scanline unit in XY for- 
mat (bitmap) or for each pixel value in Z format. The macro or function can 
return either LSBFirst or MSBFirst. 

BitaafXJnit {display) 

int XBitmapUmt(itsplay) 
Display ^display; 

Both return the size of a bitmap's scanline unit in bits. The scanline is calcu- 
lated in multiples of this value. 

BitaapBitOxdar (display) 

int XBitmapBitQrder(<^tsp%) 
Display ^display; 

Within each bitmap unit, the left-most bit in the bitmap as displayed on the 
screen is either the least-significant or most-significant bit in the unit. This 
macro or function can return LSBFirst or MSBFirst. 

BitmatlBadidisplay) 

int XBitmapPad(display) 
Display ^display; 
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Each scanline must be padded to a multiple of bits returned by this macro or 
function. 

DiaplayHeight (<<is;rfay, screenjtumber) 

int XI>isplay Height (<{tsf72ay, screenjiumher) 
Display ^display; 
int screenjiumher; 

Both return an integer that describes the height of the screen in pixels. 

DisplayB&i^tMAi display, screenjiumher) 

int XDisplayHdghtMM (<2is^2ay, screenjiumher) 
Display ^display; 
int screenjiumher; 

Both return the height of the specified screen in millimeters. 

DisplA'^idth {display, screenjiumher) 

int XDisplayWidth(itsp/ay, screenjiumher) 
EHsplay * display; 
int screenjiumher; 

Both return the width of the screen in pixels. 

Displx^idtUMi display, screenjiumher) 

int XDisplayWidthMM((ltsp2ay, screenjiumher) 
Display ^display; 
int screenjiumher; 

Both return the width of the specified screen in millimeters. 
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Screen Information Macros 

The following lists the C language macros, their corresponding function 
equivalents that are for other language bindings, and what data they both can 
return. These macros or functions all take a pointer to the appropriate screen 
structure. 

BlackPlxalOfSoTMn ( screen) 

unsigned long X61ackPixelQfScreen(screen) 
Screen ^screen; 

Both return the black pixel value of the specified screen. 

Whit«Pix»10£Sc£<Mn (screen) 

unsigned long XWhitePixelQfScreen(scfie»t) 
Screen * screen; 

Both return the white pixel value of the specified screen. 

CellsOf ScTMn ( screen) 

int XCellsQfScreen(scr6en) 
Screen * screen; 

Both return the number of colormap cells in the default colormap of the 
specified screen. 

DefaultColoxnapOfScreen {screen) 

Colormap XDefaultColormapQfScreenCscrem) 
Screen *screen; 

Both return the default colormap of the specified screen. 

DefaultDeptfaOfScraen (screen) 

int XDefaultE)epthQf5creen(scfi«n) 
Screen * screen; 

Both return the depth of the root window. 
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DefaultGOOf Screen ( screen ) 

GC XDefaultGCQfScTeen(screen) 
Screen ^screen; 

Both return a default graphics context (GC) of the specified screen, which has 
the same depth as the root window of the screen. The GC must never be freed. 

DefaultVisualOf Screen ( screen) 

Visual ♦XDefaultVisualQfScreen(scfmi) 
Screen ^screen; 

Both return the default visual of the specified screen. For information on visual 
types, see "Visual Types" in Chapter 3. 

DoesBackingStore {screen) 

int XDoesBaddngStore (somt) 
Screen *screen; 

Both return a value indicating whether the screen supports backing stores. The 
value returned can be one of WhenMapped, NotUsef ul, or Always (see "Backing 
Store Attribute" in Chapter 3). 

DoesSaveOhders (screen) 

Bool XDoesSaveUnders(sciitfn) 
Screen ^screen; 

Both return a Boolean value indicating whether the screen supports save unders. 
If True, the screen supports save unders. If False, the screen does not support 
save unders (see "Save Under Hag" in Chapter 3). 

DiaplayOfScceen ( screen) 

Display *XDisplayQfScreen(screen) 
Screen * screen; 

Both return the display of the specified screen. 
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E ventMaflkOf Scceen ( screen ) 

long XEventMasicQfScreen(screen) 
Saeen ^screen; 

Both return the event mask of the root window for the specified screen at con- 
nection setup time. 

WidtfaOf Screen ( screen) 

int XWidthOf5creen(screen) 
Screen * screen; 

Both return the width of the specified screen in pixels. 

HeigfatOf Screen ( screen ) 

int XHeightOfSoreenCscTfim) 
Screen * screen; 

Both return the height of the specified screen in pixels. 

WidthM«>fScreen {screen) 

int XWidthMMQf5creen(screen) 
Screen *screen; 

Both return the width of the specified screen in millimeters. 

HeigfatMOf Screen ( screen) 

int XHeightMMQfScreen(scr^) 
Screen * screen; 

Both return the height of the specified screen in millimeters. 

HaxCmapaOf Screen ( screen) 

int XMaxCmapsQfScreen(screm) 
Screen * screen; 

Both return the maximum number of installed colormaps supported by the 
specified screen (see "Determining Resident Colormaps" in Chapter 7). 
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MlnCmapaOf Screen ( screen ) 

int XMinCmapsQfScreen(screfft) 
Screen *screen; 

Both return the minimum number of installed colormaps supported by the 
specified screen (see "Determining Resident Colormaps" in Chapter 7). 

PlaneaOfScreen (screen) 

int XPlanesQfScreen(screen) 
Screen *screen; 

Both return the depth of the root window. 

RootWindowOf Screen ( screen) 

Window XRootWindowQfScreen (screen) 
Screen * screen; 

Both return the root window of the specified screen. 
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Generating a NoOperation Protocol Request 

To execute a NoOperation protocx)! request, use XNoOp. 

moOp {display) 

Display *dispUiy; 

display Specifies the connection to the XwiN server. 

The XNopp function sends a NoOperation protocol request to the XwiN server, 
thereby exercising the connection. 
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To free any in-memory data that was created by an Xlib function, use XFree. 

XFzee (data) 
char *data; 

data Specifies a pointer to the data that is to be freed. 

The XFree function is a general-purpose Xlib routine that frees the specified 
data. You must use it to free any objects that were allocated by Xlib. 
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Closing the Display 



To close a display or disconnect from the XwiN server, use XCloseDisplay. 

XCloseDisplay (display) 
Display *dispUiy; 

display Specifies the connection to the XwiN server. 

The XCloseDisplay function closes the connection to the XwiN server for the 
display specified in the Display structure and destroys all windows, resource 
IDs ( Window , Font, Pixmap, Colonnap, Cursor, and GContext), or other 
resources that the client has created on this display, unless the close-down mode 
of the resource has been changed (see XSetCloseDownMode). Therefore, these 
windows, resource IDs, and other resources should never be referenced again or 
an error will be generated. Before exiting, you should call XCloseDisplay 
explicitly so that any pending errors are reported as XCloseDisplay performs a 
final XSync operation. 

XCloseDisplay can generate a BadGC error. 
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When the XwiN server's connection to a client is closed either by an explicit call 
to XCloseDisplay or by a process that exits, the XwiN server performs the fol- 
lowing automatic operations: 

■ It disowns all selections owned by the client (see XSetSelectionOmer). 

■ It performs an XUngrabPointer and XUngrabKeyboard if the client has 
actively grabbed the pointer or the keyboard. 

■ It performs an XUngrabServer if the client has grabbed the server. 

■ It releases all passive grabs made by the client. 

■ It marks all resources (including colormap entries) allocated by the client 
either as permanent or temporary, depending on whether the close-down 
mode is RetainPermanent or RetainTenporary. However, this does not 
prevent other client applications from explicitly destroying the resources 
(see XSetCloseDownMcxie). 

When the close-down mode is DestroyAll, the XwiN server destroys all of a 
client's resources as follows: 

■ It examines each window in the client's save-set to detennine if it is an 
inferior (subwindow) of a window created by the client. (The save-set is a 
list of other clients' windows, which are referred to as save-set windows.) 
If so, the XwiN server reparents the save-set window to the closest ances- 
tor so that the save-set window is not an inferior of a window created by 
the client. The reparenting leaves unchanged the absolute coordinates 
(with respect to the root window) of the upper-left outer comer of the 
save-set window. 

■ It performs a MapWindow request on the save-set window if the save-set 
window is unmapped. The XwiN server does this even if the save-set 
window was not an inferior of a window created by the client. 

■ It destroys all windows created by the client. 

■ It performs the appropriate free request on each nonwindow resource 
created by the client in the server (for example. Font, Pixmap, Cursor, 
Colonnap, and GContext). 
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■ It frees all colors and coloimap entries allocated by a client application. 

Additional processing occurs when the last connection to the XwiN server closes. 
An XwiN server goes through a cycle of having no connections and having some 
connections. When the last connection to the XwiN server closes as a result of a 
connection dosing with the dosejmode of DestroyAll, the XwiN server does 
the following: 

■ It resets its state as if it had just been started. The XwiN server begins by 
destroying all lingering resources from dients that have terminated in 
RetainPemnanent or RetainTenqporary mode. 

■ It deletes all but the predefined atom identifiers. 

■ It deletes all properties on all root windows (see Chapter 4). 

■ It resets all device maps and attributes (for example, key click, bell 
volume, and acceleration) as well as the access control list. 

■ It restores the standard root tiles and cursors. 

■ It restores the default font path. 

■ It restores the input focus to state PointerRoot. 

However, the XwiN server does not reset if you close a connection with a close- 
down mode set to RetalnPennanent or RetalnTeroporary. 
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Introduction 



In the XWIN System, a window is a rectangular area on the screen that lets you 
view graphic output. Client applications can display overlapping and nested 
windows that are driven by XwiN servers on one or more machines. Qients 
who want to create windows must first connect their program to the XwiN 
server by calling xppenDisplay. This chapter begins with a discussion of visual 
types and window attributes. The chapter continues with a discussion of the 
Xlib functions you can use to: 

■ Create windows 

■ Destroy windows 

■ Map windows 

■ Unmap windows 

■ Configure windows 

■ Change the stacking order 

■ Change window attributes 

■ Translate window coordinates 

This chapter also identifies the window actions that may generate events. 

Note that it is vital that your application conform to the established conventions 
for communicating with window managers for it to work well with the various 
window managers in use (see "Communicating with Window Managers" in 
Chapter 9). Toolkits generally adhere to these conventions for you, relieving 
you of the burden. Toolkits also often supersede many functions in this chapter 
with versions of their own. Refer to the documentation for the toolkit you are 
using for more information. 
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Visual Types 



On some display hardware, it may be possible to deal with color resources in 
more than one way. For example, you may be able to deal with a screen of 
either 12-bit depth with arbitrary mapping of pixel to color (pseudo-color) or 
24-bit depth with 8 bits of the pixel dedicated to each of red, green, and blue. 
These different ways of dealing with the visual aspects of the screen are called 
visuals. For each screen of the display, there may be a list of valid visual types 
supported at different depths of the screen. Because default windows and 
visual types are defined for each screen, most simple applications need not deal 
with this complexity. Xlib provides macros and functions that return the default 
root window, the default depth of the default root window, and the default 
visual type (see **Display Macros" in chapter 2 and XMatchVisuallnfo). 

Xlib uses a Visual structure that contains information about the possible color 
mapping. The members of this structure pertinent to this discussion are class, 
red_mask, green_mask, blue^mask, bits_per_rgb, and map_entries. The class 
member specifies one of the possible visual classes of the screen and can be Sta- 
ticGray, StaticColor, TrueColor, Grayscale, Pseudocolor, or 
Direct Color. 

The following concepts may serve to make the explanation of visual types 
clearer. The screen can be color or grayscale, can have a colormap that is writ- 
able or read-only, and can also have a colormap whose indices are decomposed 
into separate RGB pieces, provided one is not on a grayscale screen. This leads 
to the following diagram: 



Color Grayscale 
R/O R/W R/O R/W 



Undecom- 


Static 


Pseudo 
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Gray 
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Color 


Color 
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Scale 
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Direct 






Colormap 


Color 


Color 







Conceptually, as each pixel is read out of video memory for display on the 
screen, it goes through a look-up stage by indexing into a colormap. Colormaps 
can be manipulated arbitrarily on some hardware, in limited ways on other 
hardware, and not at all on other hardware. The visual t3^s affect the color- 
map and the RGB values in the following ways: 
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■ For Pseudocolor, a pixel value indexes a colormap to produce indepen- 
dent RGB values, and the RGB values can be changed dynamically. 

■ Grayscale is treated the same way as Pseudocolor except that the pri- 
mary that drives the screen is undefined. Thus, the client should always 
store the same value for red, green, and blue in the colormaps. 

■ For DirectColor, a pixel value is decomposed into separate RGB 
subfields, and each subfield separately indexes the colormap for the 
corresponding value. The RGB values can be changed dynamically. 

■ TrueColor is treated the same way as DirectColor except that the color- 
map has predefined, read-only RGB values. These RGB values are 
server-dependent but provide linear or near-linear ramps in each primary. 

■ StaticColor is treated the same way as Pseudocolor except that the 
colormap has predefined, read-only, server-dependent RGB values. 

■ StaticGray is treated the same way as StaticColor except that the RGB 
values are equal for any single pixel value, thus resulting in shades of 
gray. StaticGray with a two-entry colormap can be thought of as mono- 
chrome. 

The red_mask, green_mask, and blue_mask members are only defined for 
DirectColor and TrueColor. Each has one contiguous set of bits with no 
intersections. The bits j>er_rgb member specifies the log base 2 of the number 
of distinct color values (individually) of red, green, and blue. Actual RGB 
values are unsigned 16-bit numbers. The map entries member defines the 
number of available colormap entries in a newly created colormap. For 
DirectColor and TrueColor, this is the size of an individual pixel subfield. 

To obtain the visual ID from a Visual, use XVisuallDFromVisual. 

VisuallD XVisuallDFromVisual (Z7isuai) 
Visual ^visual; 

visual Specifies the visual type. 

The XVisuallDFrOTiVisual function returns the visual ID for the specified 
visual type. 
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All inputOutput windows have a border width of zero or more pixels, an 
optional background, an event suppression mask (which suppresses propagation 
of events from children), and a property list (see "Properties and Atoms" in 
Chapter 4). The window border and background can be a solid color or a pat- 
tern, called a tile. All windows except the root have a parent and are dipped 
by their parent. If a window is stacked on top of another window, it obscures 
that other window for the purpose of input. If a window has a background 
(almost all do), it obscures the other window for purposes of output. Attempts 
to output to the obscured area do nothing, and no input events (for example, 
pointer motion) are generated for the obscured area. 

Windows also have associated property lists (see "Properties and Atoms" in 
Chapter 4). 

Both inputCXitput and InputOnly windows have the following conunon attri- 
butes, which are the only attributes of an InputOnly window: 

■ win-gravity 

■ event-mask 

■ do-not-propagate-mask 

■ override-redirect 

■ cursor 

If you specify any other attributes for an InputOnly window, a BadMatch error 
results. 

InputOnly windows are used for controlling input events in dtuations where 
InputOutput windows are unnecessary. InputOnly windows are invisible; can 
only be used to control such things as cursors, input event generation, and grab- 
bing; and cannot be used in any graphics requests. Note that InputOnly win- 
dows cannot have InputOutput windows as inferiors. 

Windows have borders of a programmable width and pattern as well as a back- 
ground pattern or tile. 

Pixel values can be used for solid colors. 



The background and border pixmaps can be destroyed immediately after creat- 
ing the window if no further explicit references to tiiem are to be made. 
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The pattern can either be relative to the parent or absolute. If ParentRelative, 
the parent's background is used. 

When windows are first created, they are not visible (not mapped) on the 
screen. Any output to a window that is not visible on the screen and that does 
not have backing store will be discarded. 

An application may wish to create a window long before it is mapped to the 
screen. When a window is eventually mapped to the screen (using XMapWin- 
dow), the XwiN server generates an Expose event for the window if backing 
store has not been maintained. 

A window manager can override your choice of size, border width, and position 
for a top-level window. Your program must be prepared to use the actual size 
and position of the top window. It is not acceptable for a client application to 
resize itself unless in direct response to a human command to do so. Instead, 
either your program should use the space given to it, or if the space is too small 
for any useful work, your program might ask the user to resize the window. 
The border of your top-level window is considered fair game for window 
managers. 

To set an attribute of a window, set the appropriate member of the XSetWin- 
dowAttributes structure and OR in the corresponding value bitmask in your 
subsequent calls to XCreateWindow and XChangeWindowAttrdLbutes, or use one 
of the other convenience fimctions that set the appropriate attribute. The sym- 
bols for the value mask bits and the XSetWindowAttributes structure are: 

/* Window attribute value mask bits */ 



#de£ine 


CNBackPi3anap 


(1L«0) 


#de£ine 


CWBackPixel 


(1L«1) 


#define 


CMBorderPixmap 


(1L«2) 


#defme 


CNBorderPixttl 


(1L«3) 


#define 


CNBitGravity 


(1L«4) 


#define 


CMWtnGravity 


(1L«5) 


#define 


CNBacskingStore 


(1L«6) 


#define 


CNBaokingP lanes 


(1L«7) 


#de£ine 


CNBackin^ixsl 


(1L«8) 
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#define CITOverrickdtodirect (1L«9) 

#define CMSaveUhder (1L«10) 

#define CNBventMask (1L«11) 

#de£ine CNDontPropagate (1L«12) 

#define CWColoznap (1L«13) 

#define CNCursor (1L«14) 



/* Values */ 

t:ypedef struct ( 

Pixmi^ backgroundjpjjonap; 

unsigned long backgrouixTpixel; 

Pixmap borderjpixmap; 

unsigned long bozderjpixiel; 

int bit jgravity; 

int winjgravity; 

int backingjBttore; 

unsigned long backing^planes; 

unsigned long baG]cing_j>ixel; 

Bool savejonder; 

long event jaaslc; 

long dojnotjpxopagatejnask; 

Bool override^redirect; 

Colomap colozmap; 

Cursor cursor; 
} XSetWindowAttrihutes; 

The following lists the defaults for each window attribute and indicates whether 
the attribute is applicable to InputOutput and InputOnly windows: 



Attribute Default InputOutput InputOnly 



/* background. None, or ParentBelative */ 
/* background pixel V 

/* border of the idndow or Cqp^^romParent */ 
/* border pixel value */ 
/* one of bit gravity values */ 
/* one of the window gravity values */ 
/* NotUseful, IftienMi^jped, Always */ 
/* planes to be preserved if possible */ 
/* value to use in restoring planes */ 
/* should bits under be saved? (popups) */ 
/* set of events that should be saved */ 
/* set of events that should not propagate */ 
/* boolean value for overridejredirect */ 
/* color map to be associated with window */ 
/* cursor to be displayed (or Ncxie) */ 



background-pixmap 

background-pixel 

border-pixmap 

border-pixel 



None 

Undefined 

CopyFroraParent 

Undefined 



Yes No 

Yes No 

Yes No 

Yes No 
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Attribiifp 


Default 






bit-gravity 


ForgetGravity 


Vac 

les 


JNO 


win-gravity 


NorthWestGravity 


Yes 


Yes 


backing-store 


NotUseful 


Yes 


No 


L/CtV.IULl Ig-L/lCll IC9 


All onpc 
JrxMi. Lulled 


Yes 


No 


backing-pixel 


zero 


Yes 


No 


save-under 


False 


Yes 


No 


event-mask 


empty set 


Yes 


Yes 


do-not-propagate-mask 


empty set 


Yes 


Yes 


override-redirect 


False 


Yes 


Yes 


colormap 


CopyFrOTiParent 


Yes 


No 


cursor 


None 


Yes 


Yes 



Background Attribute 

Only Ir^utOutput windows can have a background. You can set the back- 
ground of an ir^vttOutput window by using a pixel or a pixmap. 

The background-pixmap attribute of a window specifies the pixmap to be used 
for a window's background. This pixmap can be of any size, although some 
sizes may be faster than others. The background-pixel attribute of a window 
specifies a pixel value used to paint a window's background in a single color. 

You can set the background-pixmap to a pixmap. None (default), or ParentRe- 
lative. You can set the background-pixel of a window to any pixel value (no 
default). If you specify a background-pixel, it overrides either the default 
background-pixmap or any value you may have set in the background-pixmap. 
A pixmap of an undefined size that is filled with the backgroimd-pixel is used 
for the background. Range checking is not performed on the background pixel; 
it simply is truncated to the appropriate number of bits. 

If you set the background-pixmap, it overrides the default The backgroimd- 
pixmap and the window must have the same depth, or a BadMatch error 
results. If you set background-pixmap to None, the window has no defined 
background. If you set ttie background-pixmap to ParentRelative: 



Window Functions 



3-7 



Window Attributes 



■ The parent window's background-pixmap is used. The child window, 
however, must have the same deptti as its parent, or a BadMatch error 
results. 

■ If the parent window has a background-pixmap of None, the window also 
has a background-pixmap of None. 

■ A copy of the parent window's background-pixmap is not made. The 
parent's background-pixmap is examined each time the child window's 
background-pixmap is required. 

■ The background tile origin always aligns with the parent window's back- 
ground tile origin. If the background-pixmap is not ParentRelative, the 
background tile origin is the child window's origin. 

Setting a new background, whether by setting background-pixmap or 
background-pixel, overrides any previous background. The background-pixmap 
can be freed immediately if no further explicit reference is made to it (the XwiN 
server will keep a copy to use when needed). If you later draw into the pixmap 
used for the background, what happens is undefined because the X implementa- 
tion is free to make a copy of the pixmap or to use the same pixmap. 

When no valid contents are available for regions of a window and either the 
regions are visible or the server is maintaining backing store, the server 
automatically tiles the regions with the window's background unless the win- 
dow has a background of None. If the background is None, the previous screen 
contents from other windows of the same depth as the window are simply left 
in place as long as the contents come from the parent of the window or an infe- 
rior of the parent. Otherwise, the initial contents of the exposed regions are 
undefined. Esqpose events are then generated for the regions, even if the 
background-pixmap is None (see Chapter 8). 

Border Attribute 

Only InputOutput windows can have a border. You can set the border of an 
InputOutput window by using a pixel or a pixmap. 

The border-pixmap attribute of a window specifies the pixmap to be used for a 
window's border. The border-pixel attribute of a window specifies a pixmap of 
undefined size filled with that pixel be used for a window's border. Range 
checking is not performed on the background pixel; it simply is truncated to the 
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appropriate number of bits. The border tile origin is always the same as the 
background tile origin. 

You can also set the border-pixmap to a pixmap of any size (some may be faster 
than others) or to CopyFrcMtiParent (default). You can set the border-pixel to 
any pixel value (no default). 

If you set a border-pixmap, it overrides the default. The border-pixmap and the 
window must have the same depth, or a BadMatch error results. If you set the 
border-pixmap to CopyFrcMrtParent, the parent window's border-pixmap is 
copied. Subsequent changes to the parent window's border attribute do not 
affect the child window. However, the child window must have the same depth 
as the parent window, or a BadMatch error results. 

The border-pixmap can be freed immediately if no further explicit reference is 
made to it. If you later draw into the pixmap used for the border, what hap- 
pens is undefined because the X implementation is free either to n\ake a copy of 
the pixmap or to use the same pixmap. If you specify a border-pixel, it over- 
rides either the default border-pixmap or any value you may have set in the 
border-pixmap. All pixels in the window's border will be set to the border- 
pixel. Setting a new border, whether by setting border-pixel or by setting 
border-pixmap, overrides any previous border. 

Chitput to a window is always clipped to the inside of the window. Therefore, 
graphics operations never affect the window border. 

Gravity Attributes 

The bit gravity of a window defines which region of the window should be 
retained when an InputOutput window is resized. The default value for the 
bit-gravity attribute is ForgetGravity. The window gravity of a window 
allows you to define how tiie InputOutput or inputOnly window should be 
repositioned if its parent is resized. The default value for the win-gravity attri- 
bute is NorthWestGravity. 

If the inside width or height of a window is not changed and if the window is 
moved or its border is changed, then the contents of the window are not lost 
but move with the window. Changing the inside width or height of the win- 
dow causes its contents to be moved or lost (depending on the bit-gravity of the 
window) and causes children to be reconfigured (depending on their win- 
gravity). For a change of width and height, the (x, y) pairs are defined: 
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NorthWestGravity 

NorthGravity 

NorthEastGravity 

WestGravity 

CenterGravity 

EastGravlty 

SouthWestGravity 

SouthGravity 

SouthEastGravity 



(0,0) 

(Width/2, 0) 
(Width, 0) 
(0, Height/2) 
(Width/2, Height/2) 
(Width, Height/2) 
(0, Height) 
(Width/2, Height) 
(Width, Height) 



When a window with one of these bit-gravity values is resized, the correspond- 
ing pair defines the change in position of each pixel in the window. When a 
window with one of these win-gravities has its parent window resized, the 
corresponding pair defines the change in position of the window within the 
parent. When a window is so repositioned, a GravityNotify event is gen- 
erated (see Chapter 8). 

A bit-gravity of StaticGravity indicates that the contents or origin should not 
move relative to the origin of the root window. If the change in size of the win- 
dow is coupled with a change in position (x, y), then for bit-gravity the change 
in position of each pixel is (-x, -y), and for win-gravity the change in position 
of a child when its parent is so resized is (-x, -y). Note that StaticGravity 
still only takes effect when the width or height of the window is changed, not 
when the window is moved. 

A bit-gravity of ForgetGravity indicates that the window's contents are always 
discarded after a size change, even if a backing store or save under has been 
requested. The window is tiled with its background and zero or more Eispose 
events are generated. If no background is defined, the existing screen contents 
are not altered. Some XWIN servers may also ignore the specified bit-gravity 
and always generate E^^se events. 

A win-gravity of UnnapGravity is like NorthWestGravity (the window is not 
moved), except the child is also unmapped when the parent is resized, and an 
UnitiapNotify event is generated. 
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Backing Store Attribute 

Some implementations of the XWIN server may choose to maintain the contents 
of Ir^utOutput windows. If the XwiN server maintains the contents of a win- 
dow, the off-screen saved pixels are known as backing store. The backing store 
advises the XwiN server on what to do with the contents of a window. The 
backing-store attribute can be set to NotUsef ul (default), WhenMapped, or 
Always. 

A backing-store attribute of NotUsef ul advises the XwiN server that maintain- 
ing contents is unnecessary, although some X implementations may still choose 
to maintain contents and, therefore, not generate Expose events. A backing- 
store attribute of WhenMapped advises the XwiN server that maintaining contents 
of obscured regions when the window is mapped would be beneficial. In this 
case, the server may generate an Expose event when the window is created. A 
backing-store attribute of Always advises the XwiN server that maintaining con- 
tents even when the window is unmapped would be beneficial. Even if the win- 
dow is larger than its parent, this is a request to the XwiN server to maintain 
complete contents, not just the region within the parent window boundaries. 
While the XwiN server maintains the window's contents, E^qpose events nor- 
mally are not generated, but the XwiN server may stop maintaining contents at 
any time. 

When the contents of obscured regions of a window are being maintained, 
regions obscured by noninferior windows are included in the destination of 
graphics requests (and source, when the window is the source). However, 
regions obscured by inferior windows are not included. 

Save Under Flag 

The XwiN server implementation preserves the contents of Ir^utOutput win- 
dows under other inputOutput windows. This is not the same as preserving 
the contents of a window for you. You may get better visual appeal if transient 
windows (for example, pop-up menus) request that the system preserve the 
screen contents under them, so the temporarily obscured applications do not 
have to repaint. 
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You can set the save-under flag to True or False (default). If save-under is 
True, the XwiN server is advised that, when this window is mapped, saving the 
contents of windows it obscures would be beneficial. 



Backing Planes and Backing Pixel Attributes 

You can set backing planes to indicate (with bits set to 1) which bit planes of an 
InputOutput window hold dynamic data that must be preserved in backing 
store and during save unders. The default value for the backing-planes attribute 
is all bits set to 1. You can set backing pixel to specify what bits to use in 
planes not covered by backing planes. The default value for the backing-pixel 
attribute is all bits set to 0. The XwiN server is free to save only the specified bit 
planes in the backing store or the save under and is free to regenerate the 
remaining planes with the specified pixel value. Any extraneous bits in these 
values (that is, those bits beyond the specified depth of the window) may be 
simply ignored. If you request backing store or save unders, you should use 
these members to nunimize the amount of off-screen memory required to store 
your window. 

Event Mask and Do Not Propagate Mask Attributes 

The event mask defines which events the client is interested in for this 
InputOutput or inputOnly window (or, for some event types, inferiors of that 
window). The do-not-propagate-mask attribute defines which events should not 
be propagated to ancestor windows when no client has the event type selected 
in this InputOutput or InputOnly window. Both masks are the bitwise 
inclusive OR of one or more of the valid event mask bits. You can specify that 
no maskable events are reported by setting NoEventMask (default). 
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Override Redirect Flag 

To control window placement or to add decoration, a window manager often 
needs to intercept (redirect) any map or configure request Pop-up windows, 
however, often need to be mapped without a window manager getting in the 
way. To control whether an InputOutput or inputOnly window is to ignore 
these structure control facilities, use the override-redirect flag. 

The override-redirect flag specifies whether map and configure requests on this 
window should override a SubstructureRedlrectMask on the parent. You 
can set the override-redirect flag to True or False (default). Window managers 
use this information to avoid tampering with pop-up windows (see also Chapter 
9). 



Colormap Attribute 

The colormap attribute specifies which colormap best reflects the true colors of 
the InputOutput window. The colormap must have the same visual type as the 
window, or a BadMatch error results. XwiN servers capable of supporting multi- 
ple hardware colormaps can use this information, and window managers can 
use it for calls to XInstallColorraap. You can set the colormap attibute to a 
colormap or to CopyFroinParent (default). 

If you set the colormap to CopyFrcMnParent, the parent window's colormap is 
copied and used by its child. However, the child window must have the same 
visual type as the parent, or a BadMatch error results. The parent window must 
not have a colormap of None, or a BacMatch error results. The colormap is 
copied by sharing the colormap object between the child ^md parent, not by 
making a complete copy of the colormap contents. Subsequent changes to the 
parent window's colormap attribute do not affect the child window. 
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Cursor Attribute 

The cursor attribute specifies which cursor is to be used when the pointer is in 
the InputOutput or Ii^utOnly window. You can set the cursor to a cursor or 
None (default). 

If you set the cursor to None, the parent's cursor is used when the pointer is in 
the InputOutput or InputOnly window, and any change in the parent's cursor 
will cause an inunediate change in the displayed cursor. By calling XFreeCur- 
sor, the cursor can be freed inunediately as long as no further explicit reference 
to it is made. 
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Xlib provides basic ways for creating windows, and toolkits often supply 
higher-level functions specifically for creating and placing top-level windows, 
which are discussed in the appropriate toolkit documentation. If you do not use 
a toolkit, however, you must provide some standard information or hints for the 
window manager by using the Xlib predefined property functions (see 
Chapter 9). 

If you use Xlib to create your own top-level windows (direct children of the root 
window), you must observe the following rules so that all applications interact 
reasonably across the different styles of window management: 

■ You must never fight with the window manager for the size or placement 
of your top-level window. 

■ You must be able to deal with whatever size window you get, even if this 
means that your application just prints a message like "Please make me 
bigger" in its window. 

■ You should only attempt to resize or move top-level windows in direct 
response to a user request. If a request to change the size of a top-level 
window fails, you must be prepared to live with what you get. You are 
free to resize or move the children of top-level windows as necessary. 
(Toolkits often have facilities for automatic relayout.) 

■ If you do not use a toolkit that automatically sets standard window pro- 
perties, you should set these properties for top-level windows before map- 
ping them. 

XCreateWindow is the more general function that allows you to set specific win- 
dow attributes when you create a window. XCreateSiinpleWindow creates a 
window that inherits its attributes from its parent window. 

The XwiN server acts as if InputOnly windows do not exist for the purposes of 
graphics requests, exposure processing, and Visibilitj^otif y events. An 
InputOnly window cannot be used as a drawable (that is, as a source or desti- 
nation for graphics requests). Ir^utOnly and InputOutput windows act ident- 
ically in other respects (properties, grabs, input control, and so on). Extension 
packages can define other classes of windows. 

To create an unmapped window and set its window attributes, use 
XCreateWindow. 
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Window XCzM.t6Window(itspZay, parent, x, y, vndih, height, border joidUt, deffth, 
class, visual, vaiuemask, attributes) 
Display ^display; 
Window parent; 
int X, y; 

unsigned int mdth, height; 
unsigned int borderjmdth; 
int depth; 

unsigned int class; 

Visual *visudl 

unsigned long vaiuemask; 

XSetWindowAttributes ^attributes; 



display 
parent 

X 

y 



width 
height 



borderjvidth 
depth 

class 

visual 
vaiuemask 



Specifies the connection to the XwiN server. 
Specifies the parent window. 

Specify the x and y coordinates, which are the top-left outside 
comer of the created window's borders and are relative to the 
inside of the parent window's borders. 

Specify the width and height, which are the created window's 
inside dimensions and do not include the created window's 
borders. The dimensions must be nonzero, or a BadValue error 
results. 

Specifies the width of the aeated window's border in pixels. 

Specifies the window's depth. A depth of CopyFrcxnParent 
means the depth is taken from the parent. 

Specifies the created window's class. You can pass InputOut- 
put, InputQnly, or CopyFrcnlParent. A dass of CopyFromr- 
Parent means the class is taken from the parent. 

Specifies the visual type. A visual of CopyFroniParent means 
the visual type is taken from the parent. 

Specifies which window attributes are defined in the attributes 
argument This mask is the bitwise inclusive OR of the valid 
attribute mask bits. If vaiuemask is zero, the attributes are 
ignored and are not referenced. 
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attributes Specifies the structure from which the values (as specified by the 
value mask) are to be taken. The value mask should have the 
appropriate bits set to indicate which attributes have been set in 
the structure. 

The XCreateWindow function creates an unmapped subwindow for a specified 
parent window, returns the window ID of the created window, and causes the 
XwiN server to generate a CreateNotif y event. The created window is placed 
on top in the stacking order with respect to siblings. 

The border_width for an Ir^utOnly window must be zero, or a BadMatch error 
results. For class inputOutput, the visual type and depth must be a combina- 
tion supported for the screen, or a BadMatch error results. The depth need not 
be the same as the parent, but the parent must not be a window of class 
InputOnly, or a BadMatch error results. For an inputOnly window, the depth 
must be zero, and the visual must be one supported by the screen. If either 
condition is not mdt, a BadMatch error results. The parent window, however, 
may have any depth and class. If you specify any invalid window attribute for 
a window, a BadMatch error results. 

The created window is not yet displayed (mapped) on the user's display. To 
display the window, call XMapWindow. The new window initially uses the same 
cursor as its parent A new cursor can be defined for the new window by calling 
XDefineCursor. 

The window will not be visible on the screen unless it and all of its ancestors 
are mapped and it is not obscured by any of its ancestors. 

XCreateWindow can generate BadAlloc, BadColor, BadCursor, BadMatch, Bad- 
Pixroap, BadValue, and BadWindow errors. 

To create an unmapped InputOutput subwindow of a given parent window, 
use XCreateSinqpleWindow. 
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Windoir yCrmat^iapltlHindo^ {display, parent, x, y, width, height, border jndth, 
border, background) 

Display ^display; 
Window parent; 
int X, y ; 

unsigned int width, height; 
unsigned int borderjoidth; 
unsigned long border; 
unsigned long background; 

display Specifies the connection to the XwiN server. 

parent Specifies the parent window. 

X 

y Specify the x and y coordinates, which are the top-left outside 

comer of the new window's borders and are relative to the 
inside of the parent window's borders. 

width 

height Specify the width and height, which are the created window's 

inside dimensions and do not include the created window's 
borders. The dimensions must be nonzero, or a BadValue error 
results. 

border jmdth Specifies the width of the created window's border in pixels. 

border Specifies the border pixel value of the window. 

background Specifies the background pixel value of the window. 

The XCreateSinpleWindow function creates an unmapped InputOutput 
subwindow for a specified parent window, returns the window ID of the 
created window, and causes the XwiN server to generate a CreateNotif y event. 
The created window is placed on top in the stacking order with respect to 
siblings. Any part of the window that extends outside its parent window is 
clipped. The border_width for an InputOnly window must be zero, or a Bad- 
Match error results. XCreateSin5>leWindovr inherits its depth, class, and visual 
from its parent. All other window attributes, except background and border, 
have their default values. 

XCreateSljiipleWindow can generate BadAlloc, BadMatch, BadValue, and 
BadWindow errors. 
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Xlib provides functions that you can use to destroy a window or destroy all 
subwindows of a window. 

To destroy a window and all of its subwindows, use XDestroyWindow. 

XDestroyWindow (<2isp2ay, w) 
Display ^display; 
Window w; 

display Specifies the connection to the XwiN server. 

w Specifies the window. 

The XDestroyWindow function destroys the specified window as well as all of 
its subwindows and causes the XWDM server to generate a DestroyNotify event 
for each window. The window should never be referenced again. If the win- 
dow specified by the w argument is mapped, it is unmapped automatically. 
The ordering of the DestroyNotify events is such that for any given window 
being destroyed, DestroyNotify is generated on any inferiors of the window 
before being generated on the window itself. The ordering among siblings and 
across subhierarchies is not otherwise constrained. If the window you specified 
is a root window, no windows are destroyed. Destroying a mapped window 
will generate Expose events on other windows that were obscured by the win- 
dow being destroyed. 

XDestroyWindow can generate a BadWindow error. 

To destroy all subwindows of a specified window, use XDestroySubwindows. 

XDestroySubifineiows (display, w) 
Display ^display; 
Window w; 

display Specifies the connection to the XwiN server. 

w Specifies the window. 

The XDestroySubwindows function destroys all inferior windows of the 
specified window, in bottom-to-top stacking order. It causes the XwiN server to 
generate a Destro^otify event for each window. If any mapped subwindows 
were actually destroyed, XDestroySubwindows causes the XwiN server to gen- 
erate Expose events on the specified window. This is much more efficient than 
deleting many windows one at a time because much of the work need be 
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performed only once for all of the windows, rather than for each window. The 
subwindows should never be referenced again. 

XDestroySubwindows can generate a BadWlndow error. 
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A window is considered mapped if an XMapWindow call has been made on it. It 
may not be visible on the screen for one of the following reasons: 

■ It is obscured by another opaque window. 

■ One of its ancestors is not mapped. 

■ It is entirely clipped by an ancestor. 

Expose events are generated for the window when part or all of it becomes visi- 
ble on the screen. A client receives the Expose events only if it has asked for 
them. Windows retain their position in the stacking order when they are 
unmapped. 

A window manager may want to control the placement of subwindows. If Sub- 
structureRedirectMask has been selected by a window manager on a parent 
window (usually a root window), a map request initiated by other clients on a 
child window is not performed, and the window manager is sent a MapRequest 
event. However, if the override-redirect flag on the child had been set to True 
(usually only on pop-up menus), the map request is performed. 

A tiling window manager might decide to reposition and resize other client's 
windows and then decide to map the window to its final location. A window 
manager that wants to provide decoration might reparent the child into a frame 
first. For further information, see '^Override Redirect Flag" in this Chapter and 
Chapter 8. Only a single client at a time can select for Substruc- 
tureRedirectMask. 

Similarly, a single dient can select for ResizeRedirectMask on a parent win- 
dow. Then, any attempt to resize the window by another client is suppressed, 
and the client receives a ResizeRequest event. 

To map a given window, use XMapWindow. 

XMapWindow ( display, w) 
Display ^display; 
Window w; 

display Specifies the connection to the XwiN server. 

w Specifies the window. 
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The XMapWindow function maps the window and all of its subwindows that 
have had map requests. Mapping a window that has an unmapped ancestor 
does not display the window but marks it as eligible for display when the 
ancestor becomes mapped. Such a window is called unviewable. When all its 
ancestors are mapped, the window becomes viewable and will be visible on the 
screen if it is not obscured by another window. This function has no effect if 
the window is already mapped. 

If the override-redirect of the window is False and if some other client has 
selected SubstructureRedirectMask on the parent window, then the XwiN 
server generates a MapRequest event, and the XMapWindoif function does not 
map the window. Otherwise, the window is mapped, and the XwiN server gen- 
erates a MapNotify event. 

If the window becomes viewable and no earlier contents for it are remembered, 
the XwiN server tiles the window with its background. If the window's back- 
ground is undefined, the existing screen contents are not altered, and the XwiN 
server generates zero or more Expose events. If backing-store was maintained 
while the window was unmapped, no Expose events are generated. If 
backing-store will now be maintained, a full-window exposure is always gen- 
erated. Otherwise, only visible regions may be reported. Similar tiling and 
exposure take place for any newly viewable inferiors. 

If the window is an inputOutput window, XMapWindow generates Expose 
events on each ir^utOutput window that it causes to be displayed. If the 
client maps and paints the window and if the client begins processing events, 
the window is painted twice. To avoid this, first ask for Expose events and 
then map the window, so the client processes input events as usual. The event 
list will include Expose for each window that has appeared on the screen. The 
client's normal response to an Expose event should be to repaint the window. 
This method usually leads to simpler programs and to proper interaction with 
window managers. 

XMapWindour can generate a BadWlndow error. 
To map and raise a window, use XMapRaised. 

XMs^Raised ( display, w) 
Display ^display; 
Window w; 
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display Specifies the connection to the XWIN server. 

w Specifies the window. 

The XMapRaised function essentially is similar to XMapWindow in that it maps 
the window and all of its subwindows that have had map requests. However, it 
also raises the specified window to the top of the stack. For additional informa- 
tion, see XMac^indow. 

XMapRaised can generate multiple BadWindow errors. 

To map all subwindows for a specified window, use XMapSubwindows. 

XMa^>Subirindow8 {display, w) 
Display *dispJajf; 
Window w; 

display Specifies the connection to the XwiN server. 

w Specifies the window. 

The XMapSubwindows function maps all subwindows for a specified window in 
top-to-bottom stacking order. The XwiN server generates Es^se events on 
each newly displayed window. This may be much more efficient than mapping 
many windows one at a time because the server needs to perform much of the 
work only once, for all of the windows, rather than for each window. 

XMapSubwindows can generate a BadWindow error. 
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Xlib provides functions that you can use to unmap a window or all subwin- 
dows. 

To unmap a window, use XUnmaj^indow. 

XlJrmaplllijndaw (display, w) 
Display ^display; 
Window w; 

display Specifies the connection to the XwiN server. 

w Specifies the window. 

The XUnniapWindow function unmaps the specified window and causes the XwiN 
server to generate an UnmapNotify event. If the specified window is already 
unmapped, XUnraapWindow has no effect. Nomud exposure processing on form- 
erly obscured windows is performed. Any child window will no longer be visi- 
ble until another map call is made on the parent. In other words, the subwin- 
dows are still mapped but are not visible until the parent is mapped. Unmap- 
ping a window will generate Expose events on windows that were formerly 
obscured by it. 

XUnraapWindow can generate a BadWindow error. 

To unmap all subwindows for a specified window, use XUnraapSubwindows. 

XUnmapSuJswindows ((display, w) 
Display ^display; 
Window w; 

display Specifies the connection to the XwiN server. 

w Specifies the window. 

The XUnraapSubwindows function unmaps all subwindows for the specified win- 
dow in bottom-to-top stacking order. It causes the XwiN server to generate an 
UnmapNotify event on each subwindow and Eiqpose events on formerly 
obscured windows. Using this function is much more efficient than unmapping 
multiple windows one at a time because the server needs to perform much of 
the work only once, for all of the windows, rather than for each window. 

XUnraapSubwindows can generate a BadWindow error. 
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Xlib provides functions that you can use to move a window, resize a window, 
move and resize a window, or change a window's border width. To change one 
of these parameters, set the appropriate member of the XWindowChanges struc- 
ture and OR in the corresponding value mask in subsequent calls to XCk>n£i- 
gureWindow. The symbols for the value mask bits and the XWindowChanges 
structure are: 

/* Configure window value mask bits */ 

#define CNX 

#define CNY 

#de£ine CNNidth 

#defme CNHaight 

#define CNBordexWidth 

#define CNSibling 

#define CNStackModB 

/* Valww */ 

typedef struct ( 
int X, y; 

Int width, hsi^t; 
int borderjwidth; 
Window sibling; 
int stackjuode; 
} XifindoNChanges; 

The X and y members are used to set the window's x and y coordinates, which 
are relative to the parent's origin and indicate the position of the upper-left 
outer comer of the window. The width and height members are used to set the 
inside size of the window, not including the border, and must be nonzero, or a 
BadValue error results. Attempts to configure a root window have no effect. 

The border_width member is used to set the width of the border in pixels. Note 
that setting just the border width leaves the outer-left comer of the window in a 
fixed position but moves the absolute position of the window's origin. If you 
attempt to set the border-width attribute of an inputOnly window nonzero, a 
BadMatch error results. 



(1«0) 

(1«2) 
(1«3) 
(1«4) 
(1«5) 
(1«6) 
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The sibling member is used to set the sibling window for stacking operations. 
The stack_mode member is used to set how the window is to be restacked and 
can be set to Above, Below, Tbplf , Bottcxnlf , or Opposite. 

If the override-redirect flag of the window is False and if some other client has 
selected SubstructureRedirectMask on the parent, the XWIN server generates 
a Conf igureRequest event, and no further processing is performed. Other- 
wise, if some other client has selected ResizeRedirect:Mask on the window and 
the inside width or height of the window is being changed, a ResizeRequest 
event is generated, and the current inside width and height are used instead. 
Note that the override-redirect flag of the window has no effect on 
ResizeRedirectMask and that SubstructureRedirectMask on the parent has 
precedence over ResizeRedirectMask on the window. 

When the geometry of the window is changed as specified, the window is res- 
tacked among siblings, and a Conf igureNotify event is generated if the state 
of the window actually changes. GravityNotify events are generated after 
Conf igureNotify events. If the inside width or height of the window has actu- 
ally changed, children of the window are affected as specified. 

If a window's size actually changes, the window's subwindows move according 
to their window gravity. Depending on the window's bit gravity, the contents 
of the window also may be moved (see "Gravity Attributes" in tins chapter). 

If regions of the window were obscured but now are not, exposure processing is 
performed on these formerly obscured windows, including the window itself 
and its inferiors. As a result of increasing the width or height, exposure process- 
ing is also performed on any new regions of the window and any regions where 
window contents are lost. 

The restack check (specifically, the computation for Bottanlf , Toplf , and Oppo- 
site) is performed with respect to the window's final size and position (as con- 
trolled by the other arguments of the request), not its initial position. If a 
sibling is specified without a stack mode, a BadMatch error results. 

If a sibling and a stack_mode are specified, the window is restacked as follows: 
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Above 



Toplf 



Below 



The window is placed just above the sibling. 

The window is placed just below the sibling. 

If the sibling occludes the window, the window is placed at the 
top of the stack. 



Bottomlf If the window occludes the sibling, the window is placed at the 
bottom of the stack. 

Opposite If the sibling occludes the window, the window is placed at the 
top of the stack. If the window occludes the sibling, the win- 
dow is placed at the bottom of the stack. 

If a stack mode is specified but no sibling is specified, the window is restacked 
as follows: 

Above The window is placed at the top of the stack. 
Below The window is placed at the bottom of the stack. 
Toplf If any sibling occludes the window, the window is placed at 



Bottomlf If the window occludes any sibling, the window is placed at 
the bottom of the stack. 

Opposite If any sibling occludes the window, the window is placed at 
the top of the stack. If the window occludes any sibling, the 
window is placed at the bottom of the stack. 

Attempts to configure a root window have no effect. 

To configure a window's size, location, stacking, or border, use 
XConfigureWindow. 

XConfigureWindow(<fisp/ay, w, value jnask, values) 
Display * display; 
Window w; 

unsigned int value jnask; 
XWindowChanges *values; 
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display Spedfies the connection to the XwiN server. 

w Spedfies the window to be reconfigured. 

value jnask Specifies which values are to be set using information in the 

values structure. This niask is the bitwise inclusive OR of 
the valid configure window values bits. 

values Spedfies a pointer to the XWindowChanges structure. 



The XConf igureWindow function uses the values spedfied in the XWin- 
dowChanges structure to reconfigure a window's size, position, border, and 
stacking order. Values not specified are taken from the existing geometry of the 
window. 

If a sibling is specified without a stack_mode or if the window is not actually a 
sibling, a Bad^4atch error results. Note that the computations for Bottcxnlf , 
Toplf , and Opposite are performed with respect to the window's final 
geometry (as controlled by the other arguments passed to XConf igureWindow), 
not its initial geometry. Any backing store contents of the window, its inferiors, 
and other newly visible windows are either discarded or changed to reflect the 
current screen contents (depending on the implementation). 

XConf igureWindow can generate BadMatch, BadValue, and BadWindow errors. 

To move a window without changing its size, use XMoveWindow. 

XMoveWindo»r(ifsplkiy, w, x, y) 
Display *display; 
Window w; 
int X, y; 

display Spedfies the connection to the XwiN server. 

w Specifies the window to be moved. 

X 

y Spedfy the x and y coordinates, which define the new location 

of the top-left pixel of the window's border or the window itself 
if it has no border. 
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The XMoveWindow function moves the specified window to the specified x and y 
coordinates, but it does not change the window's size, raise the window, or 
change the mapping state of the window. Moving a mapped window may or 
may not lose the window's contents depending on if the window is obscured by 
nonchildren and if no backing store exists. If the contents of the window are 
lost, the XwiN server generates Expose events. Moving a mapped window gen- 
erates Expose events on any formerly obscured windows. 

If the override-redirect flag of the window is False and some other client has 
selected SubstructureRedlrect:Mask on the parent, the XwiN server generates 
a ConfigureRequest event, and no further processing is performed. Otherwise, 
the window is moved. 

XMoveWindow can generate a BadWindow error. 

To change a window's size without changing the upper-left coordinate, use 
XResizeWindow. 

XResizeWixKlow (its^oy, w, width, height) 
Display * display, 
Window w; 

unsigned int width, height; 

display Specifies the connection to the XwiN server. 

w Specifies the window. 

mdih 

height Specify the width and height, which are the interior dimensions 

of the window after the call completes. 

The XResizeWindow function changes the inside dimensions of the specified 
window, not including its borders. This function does not change the window's 
upper-left coordinate or the origin and does not restack the window. Changing 
the size of a mapped window may lose its contents and generate Expose events. 
If a mapped window is made smaller, changing its size generates Expose events 
on windows that the mapped window formerly obscured. 

If the override-redirect flag of the window is False and some other client has 
selected SubstructureRedirectMask on the parent, the XwiN server generates 
a ConfigureRequest event, and no further processing is performed. If either 
width or height is zero, a BadValue error results. 
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XResizeWindow can generate BadValue and BadWindow errors. 

To change the size and location of a window, use XMoveResizeWindow. 

XMoveResizeWindowC display, w, x, y, width, height) 
Display ^display; 
Window w; 
int X, y; 

unsigned int width, height; 

display Specifies the connection to the XwiN server. 

w Specifies the window to be reconfigured. 

X 

y Specify the x and y coordinates, which define the new position 

of the window relative to its parent. 

xvidih 

height Specify the width and height, which define the interior size of 

the window. 

The XMoveResizeWindow function changes the size and location of the specified 
window without raising it. Moving and resizing a mapped window may gen- 
erate an Expose event on the window. Depending on the new size and location 
parameters, moving and resizing a window may generate Expose events on 
windows that the window formerly obscured. 

If the override-redirect flag of the window is False and some other client has 
selected SubstructureRedirectMask on the parent, the XwiN server generates 
a Conf igureRequest event, and no further processing is performed. Otherwise, 
the window size and location are changed. 

XMoveResizeWindow can generate BadValue and BadWindow errors. 

To change the border width of a given window, use XSetWindowBorderWidth. 

XSetWindoi^rderWidth ((/isp/ay, w, width) 
Display ^display; 
Window w; 
unsigned int width; 
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display Specifies the connection to the XWIN server. 

w Specifies the window. 

width Specifies the width of the window border. 

The XSetWindowBorderWidth function sets the specified window's border 
width to the specified width. 

XSetWindowBorderWidth can generate a BadWindow error. 
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Xlib provides functions that you can use to raise, lower, circulate, or restack 
windows. 

To raise a window so that no sibling window obscures it, use XRaiseWindow. 

XBaiaeynindow (display, w) 
Display ^display; 
Window w; 

display Specifies the connection to the XwiN server. 

w Specifies the window. 

The XRaiseWindow function raises the specified window to the top of the stack 
so that no sibling window obscures it. If the windows are regarded as overlap- 
ping sheets of paper stacked on a desk, then raising a window is analogous to 
moving the sheet to the top of the stack but leaving its x and y location on the 
desk constant. Raising a mapped window may generate Expose events for the 
window and any mapped subwindows that were formerly obscured. 

If the override-redirect attribute of the window is False and some other client 
has selected SubstructureRedirect:Mask on the parent, the XwiN server gen- 
erates a Conf igureRequest event, and no processing is performed. Otherwise, 
the window is raised. 

XRaiseWindow can generate a BadWindow error. 

To lower a window so that it does not obscure any sibling windows, use 
XLowerWindow. 

KLoikmx^indo^ {display, w) 
Display ^display; 
Window w; 

display Specifies the connection to the XwiN server. 

w Specifies the window. 

The XLowerWindow function lowers the specified window to the bottom of the 
stack so that it does not obscure any sibling windows. If the windows are 
regarded as overlapping sheets of paper stacked on a desk, then lowering a 
window is analogous to moving the sheet to the bottom of the stack but leaving 
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its X and y location on the desk constant. Lowering a mapped window will 
generate Expose events on any windows it formerly obscured. 

If the override-redirect attribute of the window is False and some other client 
has selected SubstructureRedirectiMask on the parent, the XwiN server gen- 
erates a Conf igureRequest event, and no processing is performed. Otherwise, 
the window is lowered to the bottom of the stack. 

XLowerWindow can generate a BadWindow error. 

To circulate a subwindow up or down, use XCirculateSubwindows. 

XCirculateSubwindows {display, w, direction) 
Display ^display; 
Window w; 
int direction; 

display Specifies the connection to the XwiN server. 

XV Specifies the window. 

direction Specifies the direction (up or down) that you want to circulate 

the window. You can pass RaiseLowest or LowerHighest. 

The XCirculateSubwindows function circulates children of the specified win- 
dow in the specified direction. If you specify RaiseLowest, XCircula- 
teSubwindows raises the lowest mapped child (if any) that is occluded by 
another child to the top of the stack. If you specify LowerHighest, XCircula- 
teSubwindows lowers the highest mapped child (if any) that occludes another 
child to the bottom of the stack. Exposure processing is then performed on 
formerly obscured windows. If some other client has selected Substruc- 
tureRedirectMask on the window, the XwiN server generates a CirculateRe- 
quest event, and no further processing is performed. If a child is actually res- 
tacked, the XwiN server generates a CirculateNotify event. 

XCirculateSubwindows can generate BadValue and BadWindow errors. 

To raise the lowest mapf)ed child of a window that is partially or completely 
occluded by another child, use XCirculateSubwindowsUp. 

XCirculateSi]bwindowsl^(iis;7/ay, w) 
Display ^display; 
Window w; 
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display Spedfies the connection to the XwiN server. 

w Spedfies the window. 

The 3a:irculateSub«#indowsUp function raises the lowest mapped child of the 
spedfied window that is partially or completely ocduded by another child. 
Completely unobscured diildren are not affected. This is a convenience function 
equivalent to XCirculateSubwindof^s with RaiseLowest specified. 

XCirculateSubwindowsUp can generate a BadWindow error. 

To lower the highest mapped child of a window that partially or completely 
occludes another child, use XCirculateSubwindowsDown. 

XCiroulateSubwindowsDoim {display, w) 
Display ^display; 
Window w; 

display Spedfies the connection to the XwiN server. 

w Spedfies the window. 

The XCirculateSubwindowsDown function lowers the highest mapped child of 
the specified window that partially or completely occludes another child. Com- 
pletely unobscured children are not affected. This is a convenience function 
equivalent to XCirculateSubwindows with LowerHighest specified. 

XCirculateSubwindowsDown can generate a BadWindow error. 

To restack a set of windows from top to bottom, use XRestackWindows. 

XRestackWixidows (display, windows, nwindows); 
Display *display; 
Window windowsU; 
int nwindoios; 

display Spedfies the connection to the Xwnsr server. 

windows Spedfies an array containing the windows to be restacked. 

nwindows Spedfies the number of windows to be restacked. 
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The XRestackWindows function restacks the windows in the order specified, 
from top to bottom. The stacking order of the first window in the windows 
array is unaffected, but the other windows in the array are stacked underneath 
the first window, in the order of the array. The stacking order of the other win- 
dows is not affected. For each window in the window array that is not a child 
of the specified window, a BadMatch error results. 

If the override-redirect attribute of a window is False and some other client has 
selected SubstructureRedirectiMask on the parent, the XWIN server generates 
Conf igureRequest events for each window whose override-redirect flag is not 
set, and no further processing is performed. Otherwise, the windows will be 
restacked in top to bottom order. 

XRestackWindows can generate a BadWindow error. 
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Xlib provides functions that you can use to set window attributes. XChangeWin- 
dowAttributes is the more general function that allows you to set one or more 
window attributes provided by the XSetWindowAttributes structure. The 
other functions described in this section allow you to set one specific window 
attribute, such as a window's background. 

To change one or more attributes for a given window, use XChangeWindowAt- 
tributes. 

XChangeWindowAbtributes {display, w, valuemask, attributes) 
Display ^display; 
Window w; 

imsigned long valuemask; 
XSetWindowAttributes ^attributes; 



display Specifies the connection to the XWIN server. 

w Specifies the window. 

valuemask Specifies which window attributes are defined in the attributes 
argument. This mask is the bitwise inclusive OR of the valid 
attribute mask bits. If valuemask is zero, the attributes are 
ignored and are not referenced. The values and restrictions are 
the same as for XCreateWindow. 

attributes Specifies the structure from which the values (as specified by the 
value mask) are to be taken. The value mask should have the 
appropriate bits set to indicate which attributes have been set in 
the structure (see "Window Attributes" in this chapter). 



Depending on the valuemask, the XChangeWindowAttributes function uses the 
window attributes in the XSetWindowAttributes structure to change the 
specified window attributes. Changing the background does not cause the win- 
dow contents to be changed. To repaint the window and its background, use 
XClearWindow. Setting the border or changing the background such that the 
border tile origin changes causes the border to be repainted. Oianging the 
background of a root window to None or ParentRelative restores the default 
background pixmap. C3\anging the border of a root window to CopyFrom- 
Parent restores the default border pixmap. Changing the win-gravity does not 
affect the current position of the window. Changing the backing-store of an 
obscured window to WhenMapped or Always, or changing the backing-planes, 
backing-pixel, or save-under of a mapped window may have no immediate 
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effect. Changing the colomnap of a window (that is, defining a new map, not 
changing the contents of the existing map) generates a ColonnapNotify event. 
Changing the colormap of a visible window may have no immediate effect on 
the screen because the map may not be installed (see XInstallColonnap). 
Changing the cursor of a root window to None restores the default cursor. 
Whenever possible, you are encouraged to share colormaps. 

Multiple clients can select input on the same window. Their event masks are 
maintained separately. When an event is generated, it is reported to all 
interested clients. However, only one client at a time can select for Substruc- 
tureRedirectMask, ResizeRedirectMask, and ButtonPressMask. If a cUent 
attempts to select any of these event masks and some other client has already 
selected one, a BadAccess error results. There is only one do-not-propagate- 
mask for a window, not one per client. 

XChangeWindowAttributes can generate BadAccess, BadColor, BadCursor, 
BadMatch, BadPixraap, BadValue, and BadWindow errors. 

To set the background of a window to a given pixel, use XSetWindowBack- 
ground. 

XSetWizidoi^ckground (<2isp2ay, w, hackgroundjfixel) 
Display ^display; 
Window w; 

unsigned long hackgroundjtixel; 

display Specifies the connection to the XwiN server. 

w Specifies the window. 

background jnxel Specifies the pixel that is to be used for the background. 

The XSetWindowBackground function sets the background of the window to the 
specified pixel value. Changing the background does not cause the window 
contents to be changed. XSetWdLndowBackground uses a pixmap of undefined 
size filled with the pixel value you passed. If you try to change the backgroimd 
of an inputOnly window, a BadMatch error results. 

XSetWindowBackground can generate BadMatch and BadWindow errors. 

To set the background of a window to a given pixmap, use 
XSetWindowBackgroundPixxnap. 
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XSetWindoiiBackgroundPixmap {display, w, bacltgwundjtixmap) 
Display ^display; 
Window w; 

Bxmap background jfixmap; 

display Specifies the connection to the XwiN server. 

w Specifies the window. 

background jnxmap 

Specifies the background pixmap, ParentRelative, or 
None. 

The XSetWindowBackgroundPixraap function sets the background pixmap of the 
window to the specified pixmap. The background pixmap can immediately be 
freed if no further expUcit references to it are to be made. If ParentRelative is 
specified, the background pixmap of the window's parent is used, or on the root 
window, the default background is restored. If you try to change the back- 
ground of an ir^utOnly window, a BadMatch error results. If the background 
is set to None, the window has no defined background. 

XSetWindowBackgroundPixraap can generate BadMatch, BadPixraap, and 
BadWindow errors. 



XSetWindowBackground and XSetWindowBackgroundPixinap do not 
change the current contents of the window. 



To change and repaint a window's border to a given pixel, use XSetWin- 
dowBorder. 

XSetWindowBordiN: {display, w, border jpixel) 
Display ^display; 
Window w; 

unsigned long border jnxel; 

display Specifies the connection to the XwiN server. 

w Specifies the window. 
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border jnxel Specifies the entry in the colonnap. 

The XSetWindowBorder function sets the lx)rder of the window to the pixel 
value you specify. If you attempt to perform this on an inputOnly window, a 
BadMatch error results. 

XSetWindowBorder can generate BadMatch and BadWindow errors. 

To change and repaint the border tile of a given window, use XSetWindowBor- 
derPixmap. 

XSatWindoNBordorPixmap (<<i5p/dy, w, borderjnxmap) 
Display ^display; 
Window w; 
Pixmap horderjfixmap; 

display Specifies the connection to the XwiN server. 

w Specifies the window. 

border jpixmap Specifies the border pixmap or CopyFrcxiiParent. . 



The XSetWindowBorderPixmap function sets the border pixmap of the window 
to the pixmap you specify. The border pixmap can be freed immediately if no 
further explicit references to it are to be made. If you specify CopyFrotnParent, 
a copy of the parent window's border pixmap is used. If you attempt to per- 
form this on an InputOnly window, a BadMatch error results. 

XSetWindowBorderPixmap can generate BadMatch, BadPixnap, and BadWindow 
errors. 
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Applications, mostly window managers, often need to perform a coordinate 
transformation from the coordinate space of one window to another window or 
need to determine which subwindow a coordinate lies in. XTranslateCoordi- 
nates fulfills these needs (and avoids any race conditions) by asking the XwiN 
server to perform this operation. 

Bool XIranalateCoordinatas (display, srcjo, destjp, srcjc, srcjf, destjcjetum, 
destjfjetum, ckUdjetum) 
Display ^display; 
Window srcju, destju; 
int srcjc, src_y; 

int *destjcjretum, *destjfjtetum; 
Window *Mldjretum; 



display 

srcjv 

destjv 

srcjc 
srcjf 

dest X return 



Specifies the connection to the XwiN server. 
Specifies the source window. 
Specifies the destination window. 

Specify the x and y coordinates within the source window. 



destjfjetum Return the x and y coordinates within the destination window. 

chUdjeturn Returns the child if the coordinates are contained in a mapped 
child of the destination window. 



The XTranslateCoordinates function takes the src_x and src_y coordinates 
relative to the source window's origin and returns these coordinates to 
dest_x_retum and dest j>r_retum relative to the destination window's origin. If 
XTranslateCoordinates returns zero, src_w and dest_w are on different 
screens, and dest_x_retum and dest__y_retum are zero. If the coordinates are 
contained in a mapped child of dest_w, that child is returned to child_retum. 
Otherwise, child_retum is set to None. 

XTranslateCoordinates can generate a BadWindow error. 
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After you connect the display to the XwiN server and create a window, you can 
use the Xlib window information functions to: 

■ Obtain information about a window 

■ Manipulate property lists 

■ Obtain and change window properties 

■ Manipulate selections 
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Xlib provides functions that you can use to obtain information about the win- 
dow tree, the window's current attributes, the window's current geon\etry, or 
the current pointer coordinates. Because they are most frequently used by win- 
dow managers, these functions all return a status to indicate whether the win- 
dow still exists. 

To obtain the parent, a list of children, and number of children for a given win- 
dow, use XQueiryTree. 

status XQueryTree {display, w, rotitjetum, parentjetum, children jretum, nchildrenjetum) 
Display ^display; 
Window w; 
Window *root jretum; 
Window *paTentjetum; 
Window **chUdrenjetum; 
imsigned int *nchUdrenjTtum; 

display Specifies the connection to the XwiN server. 

w Specifies the window whose list of children, root, parent, and 

number of children you want to obtain. 

rootjeturn Returns the root window. 

parentjetum Returns the parent window. 

children return Returns a pointer to the list of children. 

nchildren jretum Returns the number of children. 

The XQueryTree function returns the root ID, the parent window ID, a fX)inter 
to the list of children windows, and the number of children in the list for the 
specified window. The children are listed in current stacking order, from bot- 
tommost (first) to topmost (last). XQueryTree returns zero if it fails and 
nonzero if it succeeds. To free this list when it is no longer needed, use XFree. 

To obtain the current attributes of a given window, use XGetWindowAttri- 
butes. 

status XGetWindowAttributes {display, w, window jittributesjetum) 
Display ^display; 
Window w; 

XWindowAttributes '^wmdoH; attributes return; 
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display Specifies the connection to the XwiN server. 

w Specifies the window whose current attributes you want to 

obtain. 

xvindowjittributesjreturn 

Returns the specified window's attributes in the XWindowAttri- 
butes structure. 

The XGetWindowAttributes function returns the current attributes for the 
specified window to an XWindowAttributes structure. 

t^pedef struct { 



int X, y; 


/* 


location of window */ 


int width, bei^t; 


/* 


width and hei^t of window */ 


int borderjridth; 


/* 


border width of window */ 


int dqpth; 


/* 


depth of window */ 


Visual *vi8ual; 


/* 


the associated visual structure */ 


Windoir root; 


/* 


root of screen containing window */ 


int class; 


/* 


InputOutput, InputOnly*/ 


int bitjgravity; 


/* 


one of the bit gravity values */ 


int winjgpravity; 


/* 


one of the window gravity values */ 


int backingjitore; 


/* 


NotUseful, ItienMapped, Always */ 


unsigned long backing^planes; 


/* 


planes to be preservad if possible */ 


unsigned long badcing^pixal; 


/* 


value to be used when restoring planes */ 


Bool savejunder; 


/* 


boolean, should bits under be saved? */ 


Colormap colozmap; 


/* 


color map to be associated with window */ 


Bool map_installed; 


/* 


boolean, is color map currently installed*/ 


int nfl4p_state; 


/* 


IsUhmapped, IsUhviewable, IsViewable V 


long alljsvKitjnasks; 


/* 


set of evants all people have interest in*/ 


long yourjsvantjnaslc; 


/* 


iny evant mask */ 


long dojiotjpropagatejnask; 


/* 


set of evants that should not propagate */ 


Bool ovorridBjDddirect; 


/* 


boolean value for override-redirect */ 


Screen *screen; 


/* 


back pointer to correct screen */ 



> XPVindbwAttributes; 

The X and y n\embers are set to the upper-left outer comer relative to the parent 
window's origin. The width and height members are set to the inside size of 
the window, not including the border. The border_width member is set to the 
window's border width in pixels. The depth member is set to the depth of the 
window (that is, bits per pixel for the object). The visual member is a pointer to 
the screen's associated Visual structure. The root member is set to the root 
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window of the screen containing the window. The class member is set to the 
window's class and can be either InputOutput or inputOnly. 

The bit _gravity member is set to the window's bit gravity and can be one of the 
following: 



CenterGravity 

The win _gravity member is set to the window's window gravity and can be one 
of the following: 



CenterGravity 

For additional information on gravity, see "Creating Windows" in Chapter 3. 

The backing store member is set to indicate how the XwiN server should main- 
tain the contents of a window and can be WhenMapped, Always, or iJotUseful. 
The backing_planes member is set to indicate (with bits set to 1) which bit 
planes of the window hold dynamic data that must be preserved in 
backing_stores and during save_unders. The backingjjixel member is set to 
indicate what values to use for planes not set in backingj^lanes. 

The save_under member is set to True or False. The colormap member is set 
to the colormap for the specified window and can be a colormap ID or None. 
The map_installed member is set to indicate whether the colormap is currently 
installed and can be True or False. The map_state member is set to indicate 
the state of the window and can be IsUnmapped, IsUnviewable, or isView- 
able. IsUnviewable is used if the window is mapped but some ancestor is 
unmapped. 



ForgetGravity 

NorthWestGravity 

NorthGravity 

NorthEastGravity 

WestGravity 



EastGravity 

SouthWestGravity 

SouthGravity 

SouthEastGravity 

StaticGravity 



UninapGravity 

NorthWestGravity 

NorthGravity 

NorthEastGravity 

WestGravity 



EastGravity 

SouthWestGravity 

SouthGravity 

SouthEastGravity 

StaticGravity 
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The all_event_masks member is set to the bitwise inclusive OR of all event 
masks selected on the window by all clients. The your_event_mask member is 
set to the bitwise inclusive OR of all event masks selected by the querying 
client. The do_not_propagate_mask member is set to the bitwise inclusive OR 
of the set of events that should not propagate. 

The override_redirect member is set to indicate whether this window overrides 
structure control facilities and can be True or False. Window manager clients 
should ignore the window if this member is True. 

The screen meniber is set to a screen pointer that gives you a back pointer to 
the correct screen. This makes it easier to obtain the screen information without 
having to loop over the root window fields to see which field matches. 

XGetWindowAbtributes can generate BadDrawable and BadWindow errors. 

To obtain the current geometry of a given drawable, use XGetGeoinetry. 

status XGetGeocoetryC itsp/oy, d, rootjretum, xjetum, yjretum, widthjretum, 
height jretum, border jufidthjretum, depihjretum) 
Display ^display; 
Drawable d; 
Window *rootj€tum; 
int *xjetum, *yjretum; 
unsigned int *widthjretum, *heightjetum; 
unsigned int *horderjmdthjTtum; 
unsigned int *depthjetum; 



display 
d 

rootjretum 

xjetum 
yjretum 



xvidthjreturn 
heightjretum 



Specifies the connection to the XwiN server. 

Specifies the drawable, which can be a window or a pixmap. 

Returns the root window. 

Return the x and y coordinates that define the location of the 
drawable. For a window, these coordinates specify the upper- 
left outer comer relative to its parent's origin. For pixmaps, 
these coordinates are always zero. 

Return the drawable's dimensions (width and height). For a 
window, these dimensions specify the inside size, not including 
the border. 
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border jmdth_retum 

Returns the border width in pixels. If the drawable is a pixmap, 
it returns zero. 

depth jetum Returns the depth of the drawable (bits per pixel for the object). 

The XGetGeoroetry function returns the root window and the current geometry 
of the drawable. The geometry of the drawable includes the x and y coordi- 
nates, width and height, border width, and depth. These are described in the 
argument list. It is legal to pass to this function a window whose class is 
InputOnly. 

To obtain the root window the pointer is currently on and the pointer coordi- 
nates relative to the roofs origin, use XQueryPointer. 

Bool XQueryPointer (<^tspiay, w, rootjretutn, diUdjretum, rootjcjetum, rootjfjretum, 
winjcjretum, winjfjetum, maskjretum) 
Display ^display; 
Window w; 

Window *root_retum, *chiildjetum , 
int ^Tootjcjetum, *rootjfjretum; 
int '^winjcjretum, ^winjfjetum; 
unsigned int *maskjetum) 

display Specifies the connection to the XwiN server. 

w Specifies the window. 

rootjetum Returns the root window that the pointer is in. 

child jeturn Returns the child window that the pointer is located in, if any. 

rootjcjetum 

rootjfjetum Return the pointer coordinates relative to the root window's ori- 
gin. 

winjcjetum 

winjfjetum Return the pointer coordinates relative to the specified window. 

maskjetum Returns the current state of the modifier keys and pointer but- 
tons. 
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The XQueryPointer function returns the root window the pointer is logically 
on and the pointer coordinates relative to the root window's origin. If 
XQueryPointer returns False, the pointer is not on the same screen as the 
specified window, and XQueryPointer returns None to child^retum and zero to 
win^x retum and win_y_retum. If KJueryPointer returns True, the pointer 
coordinates returned to win_x_retum and win_y_retum are relative to the ori- 
gin of the specified window, in this case, XQueryPointer returns the child that 
contains the pointer, if any, or else None to child_retum. 

XQueryPointer returns the current logical state of the keyboard buttons and 
the modifier keys in mask_retum. It sets mask_retum to the bitwise inclusive 
OR of one or more of the button or modifier key bitmasks to match the current 
state of the mouse buttons and the modifier keys. 

Note that the logical state of a device (as seen through Xlib) may lag the physi- 
cal state if device event processing is frozen (see "Pointer Grabbing" in 
Chapter 7). 

XQueryPointer can generate a BadWindow error. 
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A property is a collection of named, typed data. The window system has a set 
of predefined properties (for example, the name of a window, size hints, and so 
on), and users can define any other arbitrary information and associate it with 
windows. Each property has a name, which is an ISO Latin-1 string. For each 
named property, a unique identifier (atom) is associated with it. A property also 
has a type, for example, string or integer. These types are also indicated using 
atoms, so arbitrary new types can be defined. Data of only one type may be 
associated with a single property name. Clients can store and retrieve proper- 
ties associated with windows. For efficiency reasons, ah atom is used rather 
than a character string. XintemAtcm can be used to obtain the atom for pro- 
perty names. 

A property is also stored in one of several possible formats. The XWIN server 
can store the infonnation as 8-bit quantities, 16-bit quantities, or 32-bit quanti- 
ties. This permits the XwiN server to present the data in the byte order that the 
client expects. 



NOTE 



If you define further properties of complex type, you must encode and 
decode them yourself. These functions must be carefully written if they are 
to be portable. For further information about how to write a library extension, 
see appendix C. 

The type of a property is defined by an atom, which allows for arbitrary exten- 
sion in this type scheme. 

Certain property names are predefined in the server for commonly used func- 
tions, lite atoms for these properties are defined in <Xll/Xatom.h>. To 
avoid name dashes with user symbols, the fdefine name for each atom has the 
XA_ prefix. For definitions of these properties, see "Obtaining and Changing 
Window Properties" in Chapter 4. For an explanation of the functions that let 
you get and set much of the information storcd in these predefined properties, 
see Chapter 9. 

You can use properties to communicate other information between applications. 
The functions described in this section let you define new properties and get the 
unique atom IDs in your applications. 

Although any particular atom can have some client interpretation within each of 
the name spaces, atoms occur in five distinct name spaces within the protocol: 
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■ Selections 

■ Property names 

■ Property types 

■ Font properties 

■ Type of a CllentMessage event (none are built into the XwiN server) 

The built-in selection property names are: 

PRIMARY 
SECCMDARY 

The built-in property names are: 

CUT_BUFFERO 
CUT_BUFFER1 
CUT_BUFFER2 
CUT_BUFFER3 
CUT_BUFFER4 
CUT_BUFFER5 
CUT_BUFFER6 
CUT_BUFFER7 

rgb_best_map 
rgb_blue_map 
rgb default_map 
rgb"gray_map 



RGB_GREEN_MAP 
RGB_RED_MAP 
RESOURCE_MANAGER 
WM_CLASS 

WM_CLIENT_MACHINE 
WM_COMMAND 
WM_HINTS 
WM_ICON_NAME 
WM_ICON_SIZE 
WM_NAME 
WM_NORMAL HINTS 
WM_ZOOM_HD^ 
WM TRANSIENT FOR 



The built-in property types are: 

ARC 

ATOM 

BITMAP 

CARDINAL 

COLORMAP 

CURSOR 

DRAWABLE 



POINT 

rgb color map 
rectangle" 

STRING 
VISUALID 
WINDOW 
WM HINTS 
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FONT 

INTEGER 

PDCMAP 



WM SIZE HINTS 



The built-in font property names are: 



min_space 
norm_space 
max_spac:e 
end_space 



STRIKEOUT_DESCENT 

STRIKEOUT_ASCENT 

ITALIC_ANGLE 

X_HEIGHT 

QUAD_WIDTH 

WEIGHT 

POINT_SIZE 

RESOLUTION 

COPYRIGHT 

NOnCE 

FAMILY_NAME 

CAP HEIGHT 



SUPERSCRIPT_X 
SUPERSCRIPT_Y 



SUBSCRIPT_X 
SUBSCRIPT_Y 



UNDERLINE_POSmON 
UNDERLINE_THICKNESS 



FONT_NAME 
FULL NAME 



For further information about font properties, see "Font Metrics" in Chapter 6. 
To return an atom for a given name, use XIntemAtcm. 

Atom XIntemAtom ( display, etomjuone, otdy_^_exists) 



aUmjiame Specifies the name associated with ti\e atom you want returned. 

ordyjfjxists Specifies a Boolean value that indicates whether xinternAtom 
creates the atom. 

The XXntemAtcxn function returns the atom identifier associated with the 
specified atom_name string. If only_if_exists is False, the atom is created if it 
does not exist. Therefore, XInternAtcni can return None. You should use a 
null-terminated ISO Latin-1 string for atom_name. Case matters; the strings 
thing, Thing, and thinG all designate different atoms. The atom will remain 
defined even after the client's connection doses. It will become undefined only 
when the last connection to the XwiN server doses. 
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Dis{day *display; 
char *ebm_name; 
Bool onhf_if_exists; 



display 



Spedfies the connection to the XwiN server. 



Propertias and Atoms 



XlnternAton can generate BadAlloc and BadValue errors. 

To return a name for a given atom identifier, use XGetAtdnNama. 

char *lKGietlitoa»amB {display, atom) 
Display *display; 
Atom atom; 

display Specifies the connection to the XwiN server. 

atom Specifies the atom for the property name you want returned. 

The XGetAtcxroName function returns the name associated with the specified 
atom. To free the resulting string, call XFree. 

XGetJltoinNaine can generate a BadAtom error. 
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You can attach a property list to every window. Each property has a name, a 
type, and a value (see "Properties and Atoms" in Qiapter 4). The value is an 
array of 8-bit, 16-bit, or 32-bit quantities, whose interpretation is left to the 
clients. 

Xlib provides functions that you can use to obtain, change, update, or inter- 
change window properties. In addition, Xlib provides other utility functions for 
predefined property operations (see Chapter 9). 

To obtain the type, format, and value of a property of a given window, use 
XGetWindowProperty. 

int XGetWixidk>iiProperty(i^fsp2ay, w, property, longjoffset, longjengih, delete, reqjype, 
acUudJypejetum, actual Jormatjetum, nitemsjretum, hytesjifterjretum, 
prop_retuni) 

Display ^display; 

Window w; 

Atom property) 

long longjjffset, kmgjength; 

Bool delete; 

Atom reqjype; 

Atom *actual_type_retum; 

int^achul Jormatjetum', 

iinsigned long *nitemsjretum; 

imsigned long *bytesjifterjetum; 

unsigned char **propjvtum; 

Specifies the connection to the XWIN server. 
Specifies the window whose property you want to obtain. 
Specifies the property name. 

Specifies the offset in the specified property (in 32-bit quantities) 
where the data is to be retrieved. 

longjength Specifies the length in 32-bit multiples of the data to be 
retrieved. 

delete Specifies a Boolean value that determines whether the property 

is deleted. 



display 
w 

•property 
longj)ffset 
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^^^JVP^ Specifies the atom identifier associated with the property type or 

AnyPropertyType . 

actual Jypejreturn 

Returns the atom identifier that defines the actual type of the 
property. 

actual Jormat_retum 

Returns the actual format of the property. 

nitemsjretum Returns the actual number of 8-bit 16-bit, or 32-bit items stored 
in the prop_retum data. 

bytesjLfterjetum 

Returns the number of bytes remaining to be read in the pro- 
perty if a partial read was performed. 

propjetum Returns a pointer to the data in the specified format. 

The XGetWindowProperty function returns the actual type of the property; the 
actual format of the property; the number of 8-bit, 16-bit, or 32-bit items 
transferred; the number of b3rtes remaining to be read in the property; and a 
pointer to the data actually returned. XGetWindowProperty sets the return 
arguments as follows: 

■ If the specified property does not exist for the specified window, XGetWin- 
dowProperty returns None to actual_type_retum and the value zero to 
actual_format_retum and bytes_after_retum. The nitemsjretum argument 
is empty. In this case, the delete argument is ignored. 

■ If the specified property exists but its type does not match the specified 
type, XGetWindowProperty returns the actual property type to 
actual type retum, the actual property format (never zero) to 
actual_format_retum, and the property length in bytes (even if the 
actual_format_retum is 16 or 32) to bytes_^ter_retum. It also ignores the 
delete argument The nitemsjretum argument is empty. 

■ If the specified property exists and either you assign AnyPropertyType to 
the req_type argument or the specified type matches the actual property 
type, XGetWindowProperty returns the actual property type to 
actual_type_retum and the actual property format (never zero) to 
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actual_format_retiim. It also returns a value to bytes_af ter_retum and 
nitems^retum, by defining the following values: 

N = actual length of the stored property in b3rtes 

(even if the format is 16 or 32) 
1 = 4* long_off set 

T = N-I 

L = MINIMUMd, 4 ♦ long^length) 
A = N - (I + L) 

The returned value starts at byte index I in the property (indexing from 
zero), and its length in bytes is L. If the value for long_offset causes L to 
be negative, a BadValue error results. The value of bytes_after_retum is 
A, giving the number of trailing unread b3rtes in the stored property. 

XGetWindowProperty always allocates one extra byte in prop_retum (even if 
the property is zero length) and sets it to ASCII null so that simple properties 
consisting of characters do not have to be copied into yet another string before 
use. If delete is True and bytes_after_retum is zero, XGetWindowProperty 
deletes the property from the window and generates a PropertyNotify event 
on the window. 

The function returns Success if it executes successfully. To free the resulting 
data, use XFree. 

XGetWindowProperty can generate BadAtom, BadValue, and BadWindow errors. 

To obtain a given window's property list, use XListPrpperties. 

Atom *XLi8tProperti<M {display, w, nwnjrropjetum) 
Display *dispUiy; 
Window w; 
int *numjpfopjretwrn; 

display Specifies the connection to the XwiN server. 

w Specifies the window whose property list you want to obtain. 

numjpropjretum 

Returns the length of the properties array. 
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The XListProperties function returns a pointer to an array of atom properties 
that are defined for the specified window or returns NULL if no properties were 
found. To free the memory allocated by this function, use XFree. 

XListProperties can generate a BadWindow error. 

To change a property of a given window, use XChangeProperty. 

XChangaProperty (itsplay, w, property, type, format, mode, data, nelements) 
Display *disp]ay; 
Window w; 
Atom property, type; 
ini format) 
int mode; 

undgned char *data; 
int nelements; 



display Specifies the connection to the XwiN server. 

w Specifies the window whose property you want to change. 

property Specifies the property name. 

type Specifies the type of the property. The XwiN server does not 

interpret the type but simply passes it back to an application 
that later calls XGetWindowProperty. 

format Specifies whether the data should be viewed as a list of 8-bit, 

16-bit, or 32-bit quantities. Possible values are 8, 16, and 32. 
This information allows the XwiN server to correctly perform 
byte-swap operations as necessary. If the format is 16-bit or 32- 
bit, you must explicitly cast your data pointer to a (char *) in the 
call to XChangeProperty. 

mode Specifies the mode of the operation. You can pass PropModeRe- 

place, PropModePrepetid, or PropMode^pend. 

data Specifies the property data. 

nelements Specifies the number of elements of the specified data format. 

The XChangeProperty function alters the property for the specified window 
and causes the XwiN server to generate a PropertyNotify event on that win- 
dow. XChangeProperty performs the following: 
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■ If mode is PropMcxieReplace, XChangeProperty discards the previous 
property value and stores the new data. 

■ If mode is PropMcxiePrepend or PropModeAppend, XChangeProperty 
inserts the specified data before the beginning of the existing data or onto 
the end of the existing data, respectively. The type and format must 
match the existing property value, or a BadMatch error results. If the pro- 
perty is undefined, it is treated as defined with the correct type and for- 
mat with zero-length data. 

The lifetime of a property is not tied to the storing client. Properties remain 
until exphdtly deleted, until the window is destroyed, or until the server resets. 
For a discussion of what happens when the connection to the XWIN server is 
closed, see "Qosing the Display" in Chapter 2. The maximum size of a property 
is server dependent and can vary dynamically depending on the amount of 
memory the server has available. (If there is insufficient space, a BadAlloc 
error results.) 

XChangeProperty can generate BadAlloc, BadAtom, BadMatch, BadValue, and 
BadWindow errors. 

To rotate a window's property list, use XRotateWindowProperties. 

XRotateWindowProperties {display, w, properties, numjnvp, nposUions) 
Display ^display; 
Window w; 
Atom propertiesU) 
int numjnvp; 
int npositions; 

display Specifies the connection to the XwiN server. 

tv Specifies the window. 

properties Specifies the array of properties that are to be rotated. 
numjprop Specifies the length of the properties array. 
npositions Specifies the rotation amount. 

The XRotateWlndoi^ropertles function allows you to rotate properties on a 
window and causes the XwiN server to generate PropertyNotify events. If the 
property names in the properties array are viewed as being numbered starting 
from zero and if there are num_prop property names in the list, then the value 
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associated with property name I becomes the value associated with property 
name (I + npositions) mod N for all I from zero to N - 1. The effect is to rotate 
the states by npositions places around the virtual ring of property names (right 
for positive npositions, left for negative npositions). If npositions mod N is 
nonzero, the XwiN server generates a Propert^otify event for each property 
in the order that they are listed in the array. If an atom occurs more than once 
in the list or no property with that name is defined for the window, a BadMatch 
error results. If a BadAtom or BadMatch error results, no properties are 
changed. 

XRotateWindowProperties can generate BadAtc^, BadMatch, and BadWindow 
errors. 

To delete a property on a given window, use XDeleteProperty. 

XDeletttProperty ( display, w, property) 
Display ^display; 
Window w; 
Atom property; 

display Sf)ecifies the connection to the XwiN server. 

w Specifies the window whose property you want to delete. 

property Specifies the property name. 

The XDeleteProperty function deletes the specified property only if the pro- 
perty was defined on the specified window and causes the XwiN server to gen- 
erate a PropertyNotify event on the window unless the property does not 
exist, 

XDeleteProperty can generate BadAtom and BadWindow errors. 
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Selections are one method used by applications to exchange data. By using the 
property mechanism, applications can exchange data of arbitrary types and can 
negotiate the type of the data. A selection can be thought of as an indirect pro- 
perty with a dynamic type. That is, rather than having the property stored in 
the XWIN server, the property is maintained by some client (the owner). A 
selection is global in nature (considered to belong to the user but be maintained 
by clients) rather than being private to a particular window subhierarchy or a 
particular set of clients. 

Xlib provides functions that you can use to set, get, or request conversion of 
selections. This allows applications to implement the notion of current selection, 
which requires that notification be sent to applications when they no longer 
own the selection. Applications that support selection often highlight the 
current selection and so must be informed when another application has 
acquired the selection so that they can unhighlight the selection. 

When a client asks for the contents of a selection, it specifies a selection target 
type. This target type can be used to control the transmitted representation of 
the contents. For example, if the selection is "the last thing the user clicked on" 
and that is currently an image, then the target type might specify whether the 
contents of the image should be sent in XY format or Z format. 

The target type can also be used to control the class of contents transmitted, for 
example, asking for the "looks" (fonts, line spacing, indentation, and so forth) of 
a paragraph selection, not the text of the paragraph. The target type can also be 
used for other purposes. The protocol does not constrain the semantics. 

To set the selection owner, use XSetSelectionOwner. 

XSetSeleotionOnner (i^tsfiky, sdectkm, owner, time) 



Display ^display; 
Atom sdectkm', 
Windbw owner; 
Hme time; 



display 
selection 



Specifies the connection to the XwiN server. 
Specifies the selection atom. 

Specifies the owner of the specified selection atom. You can 
pass a window or None. 



oumer 
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time Specifies the time. You can pass either a timestamp or Current- 

Time. 

The XSetSelectionOwner function changes the owner and last-change time for 
the specified selection and has no effect if the specified time is earlier than the 
current last-change time of the specified selection or is later than the current 
XWIN server time. Otherwise, the last-change time is set to the specified time, 
with CurrentTiroe replaced by the current server time. If the owner window is 
specified as None, then the owner of the selection becomes None (that is, no 
owner). Otherwise, the owner of the selection becomes the client executing the 
request. 

If the new owner (whether a client or None) is not the same as the current 
owner of the selection and the current owner is not None, the current owner is 
sent a SelectionClear event. If the client that is the owner of a selection is 
later terminated (that is, its connection is closed) or if the owner window it has 
specified in the request is later destroyed, the owner of the selection automati- 
cally reverts to None, but the last-change time is not affected. The selection 
atom is uninterpreted by the XwiN server. XGetSelectionOwner returns the 
owner window, which is reported in SelectionRequest and SelectionClear 
events. Selections are global to the XwiN server. 

XSetSelectionOwner can generate BadAtom and BadWindow errors. 

To return the selection owner, use XGetSelectionCXmer. 

Window TSamt8%lBC±ioTiOiaTmr{ display/, seUction) 
Display ^display; 
Atom selection) 

display Specifies the connection to the XwiN server. 

selection Specifies the selection atom whose owner you want returned. 

The XGetSelectionOwner function returns the window ID associated with the 
window that currently owns the specified selection. If no selection was 
specified, the function returns the constant None. If None is returned, there is 
no owner for the selection. 

XGetSelectionOwner can generate a BadAtom error. 
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To request conversion of a selection, use XConvertSelection. 

XConviftrtSttlection {display, selection, target, frofierty, requestor, time) 
Display ^display; 
Atom selection, target) 
Atom property, 
Window requestor; 
Hme time; 



display 


Specifies the connection to the XwiN server. 


selection 


Specifies the selection atom. 


target 


Specifies the target atom. 


property 


Specifies the property name. You also can pass None. 


requestor 


Specifies the requestor. 


time 


Specifies the time. You can pass either a timestamp or Current- 



Time. 



XConvertSelection requests that the specified selection be converted to the 
specified target type: 

■ If the specified selection has an owner, the XwiN server sends a Selec- 
tionRequest event to that owner. 

■ If no owner for the specified selection exists, the XwiN server generates a 
Select ionNotify event to the requestor with properly None. 

In either event, the arguments are passed on unchanged. There are two 
predefined selection atoms: PRIMARY and SECONDARY. 

XConvertSelection can generate BadAtom and BadWindour errors. 
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Introduction 



After you connect your program to the XwiN server by calling xopenDisplay, 
you can use the Xlib graphics resource functions to: 

■ Create, copy, and destroy colormaps 

■ Allocate, modify, and free color cells 

■ Read entries in a colormap 

■ Create and free pixmaps 

■ Create, copy, change, and destroy graphics contexts 

A number of resources are used when performing graphics operations in X. 
Most information about performing graphics (for example, foreground color, 
background color, line style, and so on) are stored in resources called graphics 
contexts (GC). Most graphics operations (see Chapter 6) take a GC as an argu- 
ment. Although in theory it is possible to share GCs between applications, it is 
expected that applications will use their own GCs when performing operations. 
Sharing of GCs is highly discouraged because the library may cache GC state. 

Each X window always has an associated colormap that provides a level of 
indirection between pixel values and colors displayed on the screen. Many of 
the hardware displays built today have a single colormap, so the primitives are 
written to encourage sharing of colormap entries between applications. Because 
colormaps are associated with windows, X will support displays with multiple 
colormaps and, indeed, different types of colormaps. If there are not sufficient 
colormap resources in the display, some windows may not be displayed in their 
true colors. A client or window manager can control which windows are 
displayed in their true colors if more titan one colormap is required for the color 
resources the applications are using. 

Off-screen memory or pixmaps are often used to define frequently used images 
for later use in graphics operations. Pixmaps are also used to define tiles or pat- 
terns for use as window backgrounds, borders, or cursors. A single bit-plane 
pixmap is sometimes referred to as a bitmap. 

Note that some screens have very Umited off-screen memory. Therefore, you 
should regard off-screen memory as a precious resource. 

Graphics operations can be performed to either windows or pixmaps, which col- 
lectively are called drawables. Each drawable exists on a single screen and can 
only be used on that screen. GCs can also only be used with drawables of 
matching screens and depths. 
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Xlib provides functions that you can use to manipulate a colonnap. This section 
discusses how to: 

■ Create, copy, and destroy a colonnap 

■ Allocate, modify, and free color cells 

■ Read entries in a colormap 

The following functions manipulate the representation of color on the screen. 
For each possible value that a pixel can take in a window, there is a color cell in 
the colormap. For example, if a window is 4 bits deep, pixel values 0 through 
15 are defined. A colormap is a collection of color cells. A color cell consists of 
a triple of red, green, and blue. As each pixel is read out of display memory, its 
value is taken and looked up in the colormap. The values of the cell determine 
what color is displayed on the screen. On a multiplane display with a black- 
and-white monitor (with grayscale but not color), these values can be combined 
to determine the brightness on the screen. 

Screens always have a default colormap, and programs typically allocate cells 
out of this colormap. You should not write applications that monopolize color 
resources. On a screen that either cannot load the colormap or cannot have a 
fully independent colormap, only certain kinds of allocations may work. 
Depending on the hardware, one or more colormaps may be resident (installed) 
at one time. To install a colormap, use XlnstallColorxnap. The 
Def aultColonnap macro returns the default colormap. The DefaultVisual 
macro returns the default visual type for the specified screen. Colormaps are 
local to a particular screen. Possible visual types are StaticGray, Grayscale, 
StaticColor, Pseudocolor, TrueColor, or DirectColor (see "Visual Types" 
in Chapter 3). 

The functions discussed in this section operate on an XColor structure, which 
contains: 

typedef struct { 

unsigEwd long pixel; /* pixel value */ 

unsigned short red, green, blue; rgb values */ 

char flags; /* DoBed, DoGreen, DoBlue */ 

char pad; 
> XColor; 
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The red, green, and blue values are scaled between 0 and 65535. On full in a 
color is a value of 65535 independent of the number of bits actually used in the 
display hardware. Half brightness in a color is a value of 32767, and off is 0. 
This representation gives uniform results for color values across different 
screens. In some functions, the flags member controls which of the red, green, 
and blue members is used and can be one or more of DoRed, DoGreen, and DoB- 
lue. 

The introduction of color changes the view a programmer should take when 
dealing with a bitmap display. For example, when printing text, you write a 
pixel value, which is defined as a specific color, rather than setting or clearing 
bits. Hardware will impose limits (the number of significant bits, for example) 
on these values. Typically, one allocates color cells or sets of color cells. If 
read-only, the pixel values for these colors can be shared among multiple appli- 
cations, and the RGB values of the cell cannot be changed. If read/write, they 
are exclusively owned by the program, and the color cell associated with the 
pixel value may be changed at will. 

Creating, Copying, and Destroying Colormaps 

To create a colormap for a screen, use XCreateColorniap. 

Colozma^ HCCrBatmColormap {display, w, visual, attoc) 
Display *display; 
Window w; 
Visual ^visual; 
int alloc; 

Specifies the connection to the XwiN server. 

Specifies the window on whose screen you want to create a 
colormap. 

Specifies a pointer to a visual type supported on the screen. If 
the visual type is not one supported by the screen, a BadMatch 
error results. 

Specifies the colormap entries to be allocated. You can pass 
AllocNone or AllocAll. 



display 
w 

visual 
alloc 
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The XCreateColonnap function creates a coloimap of the specified visual type 
for the screen on which the specified window resides and returns the colormap 
ID associated with it. Note that the specified window is only used to detennine 
the screen. 

The initial values of the colormap entries are undefined for the visual classes 
Grayscale, Pseudocolor, and DirectColor. For StaticGray, StaticColor, 
and TrueColor, the entries have defined values, but those values are specific to 
the visual and are not defined by X. For StaticGray, StaticColor, and 
TrueColor, alloc must be AllocNone, or a Bad^datch error results. For the 
other visual classes, if alloc is AllocNone, the colormap initially has no allocated 
entries, and clients can allocate them. For information about the visual types, 
see "Visual Types" in Chapter 3. 

If alloc is AllocAll, the entire colormap is allocated writable. The initial values 
of all allocated entries are undefined. For Grayscale and Pseudocolor, the 
effect is as if an XAllocColorCells call returned all pixel values from zero to N 
- 1, where N is the colormap entries value in the specified visual. For 
DirectColor, the effect is as if an XAllocColorPlanes call returned a pixel 
value of zero and red__mask, green_mask, and blue_mask values containing the 
same bits as the corresponding masks in the specified visual. However, in all 
cases, none of these entries can be freed by using XFreeColors. 

XCreateColormap can generate BadAlloc, BadMatch, BadValue, and BadWin- 
dow errors. 

To create a new colormap when the allocation out of a previously shared color- 
map has failed because of resource exhaustion, use XCc^yColormapAndFree. 

Colormap XCppyColormsqpAndFree (display, cdormap) 
Display ^display; 
Colonnap cdormap; 

display Specifies the connection to the XwiN server. 

colormap Specifies the colormap. 

The XCopyColorinapAndFree function creates a colormap of the same visual 
t)^ and for the same screen as the specified colormap and returns the new 
colormap ID. It also moves all of the clienf s existing allocation from the 
specified colormap to the new colormap with their color values intact and their 
read-only or writable characteristics intact and frees those entries in the 
specified colormap. Color values in other entries in the new colormap are 
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undefined. If the specified colormap was created by the client with alloc set to 
AllccAll, the new colormap is also created with AllocAll, all color values for 
all entries are copied from the specified colormap, and then all entries in the 
specified colormap are freed. If the specified colormap was not created by the 
client with AllocAll, the allocations to be moved are all those pixels and planes 
that have been allocated by the client using XAllocColor, XAllocNainedColor, 
XAllocColorCells, or XAllocColorPlanes and that have not been freed since 
they were allocated. 

XCopyColonnapAndFree can generate BadAlloc and BadColor errors. 

To set the colormap of a given window, use XSetWindowColonnap. 

XSetWlnidkyifColozmap(ilisp2ayr colormap) 
Display ^display; 
Window w; 
Colonnap colormap; 

display Specifies the connection to the XwiN server. 

to Specifies the window. 

colonnap Specifies the colormap. 

The XSetWindowColonnap function sets the specified colormap of the specified 
window. The colormap must have the same visual type as the window, or a 
BadMatch error results. 

XSetWindowColonnap can generate BadColor, BadMatch, and BadWindow 
errors. 

To destroy a colormap, use XFreeColonnap. 

XFreaColomu^ ( disjAay, colormap) 
Display * display; 
Colonnap colormap; 

display Specifies the connection to the XwiN server. 

colormap Specifies the colormap that you want to destroy. 
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The XFreeColorinap function deletes the association between the colormap 
resource ID and the colormap and frees the colormap storage. However, this 
function has no effect on the default colormap for a screen. If the specified 
colormap is an installed map for a screen, it is uninstalled (see XUnin- 
stallColormap). If the specified colormap is defined as the colormap for a 
window (by XCreateWindow, XSetWindowColonnap, or XChangeWindowAttri- 
butes), XFreeColorinap changes the colormap associated with the window to 
None and generates a ColormapNotify event. X does not define the colors 
displayed for a window with a colormap of None. 

XFreeColorinap can generate a BadColor error. 

Allocating, Modifying, and Freeing Color Cells 

There are two ways of allocating color cells: explicitly as read-only entries by 
pixel value or read /write, where you can allocate a number of color cells and 
planes simultaneously. The read/write cells you allocate do not have defined 
colors until set with XStoreColor or XStoreColors. 

To determine the color names, the XwiN server uses a color database. 

Although you can change the values in a read /write color cell that is allocated 
by another application, this is considered "antisocial" behavior. 

To allocate a read-only color cell, use XAllocColor. 

status XAlloc<k>lor {display, colormap, screen Jnjmt) 
Display ^display; 
Colonnap colormap; 
XColor *screenjnjmt; 

display Specifies the connection to the XwiN server. 

colormap Specifies the colormap. 

screenjnj>ut Specifies and returns the values actually used in the colormap. 

The XAllocColor function allocates a read-only colormap entry corresponding 
to the closest RGB values supported by the hardware. XAllocColor returns the 
pixel value of the color closest to the specified RGB elements supported by the 
hardware and returns the RGB values actually used. The corresponding 
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colormap cell is read-only. In addition, XAllocColor returns nonzero if it suc- 
ceeded or zero if it failed. 

Read-only colormap cells are shared among clients. When the last client deallo- 
cates a shared cell, it is deallocated. XAllocColor does not use or affect the 
flags in the XColor structure. 

XAllocColor can generate a BadColor error. 

To allocate a read-only color cell by name and return the closest color supported 
by the hardware, use XAllocNainedColor. 



status X2U.locNainedColor( iis^/ay, colormap, color jiame, screen_defjetum, exact _defjetum) 
EHsplay * display; 
Colormap colormap) 
char * color jiame) 

XColor *screenjiefjretum, *exact_def_retum; 

display Specifies the connection to the XwiN server. 

colormap Specifies the colormap. 

coloTjiame Specifies the color name string (for example, red) whose 

color definition structure you want returned. 

screen_defjeiurn Returns the closest RGB values provided by the hardware. 

exact _defjeturn Returns the exact RGB values. 

The XAllocNainedColor function looks up the named color with respect to the 
screen that is associated with the specified colormap. It returns both the exact 
database definition and the closest color supported by the screen. The allocated 
color cell is read-only. You should use the ISO Latin-1 encoding; uppercase and 
lowercase do not matter. 

XAllocNamedColor can generate a BadColor error. 
To look up the name of a color, use XLookupColor. 
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status XLookuqpColor ((display, colormap, color jiame, exactjiefjretum, screen JUfjretum) 
Display ^display; 
Colonnap cdonmp; 
char *ooHorjumie; 

XColor *exactjiefjetum, *screenjtefjetum) 



display Specifies the connection to the XwiN server. 

colormap Specifies the colonnap. 

color jume Specifies the color name string (for example, red) whose 

color definition structure you want returned. 

exactjlefjretum Returns the exact RGB values. 

screen Jiefjetum Returns the closest RGB values provided by the hardware. 



The XLookupColor function looks up the string name of a color with respect to 
the screen associated with the specified colormap. It returns both the exact 
color values and the closest values provided by the screen with respect to the 
visual type of the specified colormap. You should use the ISO Latin-1 encoding; 
uppercase and lowercase do not matter. XLookiiqpColor returns nonzero if the 
name existed in the color database or zero if it did not exist. 

To allocate read/ write color cell and color plane combinations for a Pseu- 
docolor model, use X2U.locColorCells. 

status XAllooColozCella {display, colormap, contig, plane jmsksjetum, npUmes, 
pixels jretum, npixeis) 
Display ^display; 
Colormap cdormap; 
Bool contig; 

unsigned long jdanejnasksj^tumU; 
unsigned int nplanes; 
unsigned long pixelsjetuml]; 
unsigned int npixels; 

display Specifies the connection to the XwiN server. 

colormap Specifies the colormap. 
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contig Specifies a Boolean value that indicates whether the planes must 

be contiguous. 

plane jnaskjretum 

Returns an array of plane masks. 

nplanes Specifies the number of plane masks that are to be returned in 

the plane masks array. 

jrixekjretum Returns an array of pixel values. 

npixeb Specifies the number of pixel values that are to be returned in 

the pixels_retum array. 

The XAllocColorCells function allocates read/write color cells. The number 
of colors must be positive and the number of planes nonnegative, or a Bad- 
Value error results. If ncolors and nplanes are requested, tfien ncolors pixels 
and nplane plane masks are returned. No mask will have any bits set to 1 in 
common with any other mask or with any of the pixels. By ORing together 
each pixel with zero or more masks, ncolors * 2*^"^ distinct pixels can be pro- 
duced. All of these are allocated writable by the request. For Grayscale or 
Pseudocolor, each mask has exactly one bit set to 1. For DirectColor, each 
has exactly three bits set to 1. If contig is True and if all masks are ORed 
together, a single contiguous set of bits set to 1 will be formed for Grayscale or 
Pseudocolor and three contiguous sets of bits set to 1 (one within each pixel 
subfield) for DirectColor. The RGB values of the allocated entries are 
undefined. X2U.locColorCells returns nonzero if it succeeded or zero if it 
failed. 

XAllocColorCells can generate BadColpr and BadValue errors. 

To allocate read /write color resources for a DirectColor model, use XAlloc- 
ColorPlanes. 
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status XAllooColorP lanes {displaif, colormap, cantig, pixeUjretum, ncdlors, nreds, ngreens, 
nbiues, rmaskjretum, gmaskjretum, hmaskjretum) 
Display ^display; 
Colonnap colormap; 
Bool cxmtig; 

unsigned long pixels_retum[]; 
int ncdbrs; 

int nreds, ngreens, nbiues; 

unsigned long ^rmaskjretum, ^gmaskjretum, ^hmaskjretum; 



display 

colormap 

contig 

pixelsjetum 

ncolors 

nreds 

ngreens 

nbiues 

rmaskjetum 
gmaskjeturn 
bmask return 



Specifies the connection to (he XwiN server. 
Specifies the colonnap. 

Specifies a Boolean value that indicates whether the planes must 
be contiguous. 

Returns an array of pixel values. XAllocColorPlanes returns 
the pixel values in this array. 

Specifies the number of pixel values that are to be returned in 
the pixels_retum array. 



Specify the number of red, green, and blue planes. The value 
you p>ass must be nonnegative. 



Return bit masks for the red, green, and blue planes. 



The specified ncolors must be positive; and nreds, ngreens, and nbiues must be 
nonnegative, or a BadValue error results. If ncolors colors, nreds reds, ngreens 
greens, and nbiues blues are requested, ncolors pixels are returned; and the 
masks have nreds, ngreens, and nbiues bits set to 1, respectively. If contig is 
True, each mask will have a contiguous set of bits set to 1. No mask will have 
any bits set to 1 in common with any other n\ask or with any of the pixels. For 
DirectColor, each mask will lie within the corresponding pixel subfield. By 
ORing together subsets of masks with each pixel value, ncolors * 
2(nreds^ngreens+nHyss) distinct pixel values Can be produccd. All of these are allo- 
cated by the request. However, in the colormap, there are only ncolors * 2^^"^ 
independent red entries, ncolors * 2"^"^ independent green entries, and ncolors 
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* independent blue entries. This is true even for Pseudocolor. When the 
colormap entry of a pixel value is changed (using XStoreColors, XStoreColor, 
or XStoreNainedColor), the pixel is decomposed according to the masks, and 
the corresponding independent entries are updated. XAllocColorPlanes 
returns nonzero if it succeeded or zero if it failed. 

XAllocColorPlanes can generate BadColor and BadValue errors. 

To store RGB values into colormap cells, use XStoreColors. 

XStoraColors {display, colormap, color, ncolors) 
Display "^display; 
Colonnap colormap; 
XColor colorU; 
int ncaiors; 

Specifies the connection to the XwiN server. 
Specifies the colormap. 

Specifies an array of color definition structures to be stored. 

Specifies the number of XColor structures in the color definition 
array. 

The XStoreColors function changes the colormap entries of the pixel values 
specified in the pixel members of the XColor structures. You specify which 
color components are to be changed by setting DoRed, DoGreen, and/or DoBlue 
in the flags member of the XColor structures. If the colormap is an installed 
map for its screen, the changes are visible inunediately. XStoreColors changes 
the specified pixels if they are allocated writable in the colormap by any client, 
even if one or more pixels generates an error. If a specified pixel is not a valid 
index into the colormap, a BadValue error results. If a specified pixel either is 
unallocated or is allocated read-only, a BadAccess error results. If more than 
one pixel is in error, the one that gets reported is arbitrary. 

XStoreColors can generate BadAccess, BadColor, and BadValue errors. 

To store an RGB value in a single colormap cell, use XStoreColor. 

XStorsColor (display, colormap, color) 
Display *display; 
Colonnap colormap; 
XColor *color; 



display 
colormap 
color 
ncolors 
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display Specifies the connection to the XwiN server. 

colormap Specifies the colormap. 

color Specifies the pixel and RGB values. 

The XStoreColor function changes the colormap entry of the pixel value 
specified in the pixel member of the XColor structure. You specified this value 
in the pixel member of the XColor structure. This pixel value must be a 
read /write cell and a valid index into the colormap. If a specified pixel is not a 
valid index into the colormap, a BadValue error results. XStoreColor also 
changes the red, green, and /or blue color components. You specify which color 
components are to be changed by setting DoRed, DoGreen, and/or DoBlue in 
the flags member of the XColor structure. If the colormap is an installed map 
for its screen, the changes are visible inunediately. 

XStoreColor can generate BadAccess, BadColor, and BadValue errors. 

To set the color of a pixel to a named color, use XStoreNainedColor. 

XStoreNamedColor (iiispZay, colormap, color, pixel, flags) 
Display ^display; 
Colormap coiormap; 
char *cdlor; 
tinsigned long pixel; 
int flags; 



display Specifies the connection to the XwiN server. 

colormap Specifies the colormap. 

color Specifies the color name string (for example, red). 

pixd Specifies the entry in the colormap. 

flags Specifies which red, green, and blue components are set. 



The XStoreNainedColor function looks up the named color with respect to the 
screen associated with the colormap and stores the result in the specified color- 
map. The pixel argument determines the entry in the colormap. The flags 
ailment determines which of the red, green, and blue components are set 
You can set this member to the bitwise inclusive OR of the bits DoRed, DoGreen, 
and DoBlue. If the specified pixel is not a valid index into the colormap, a Bad- 
Value error results. If the specified pixel either is unallocated or is allocated 
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read-only, a BadAccess error results. You should use the ISO Latin-1 encodings- 
uppercase and lowercase do not matter. 

XStoreNamedColor can generate BadAccess, BadColor, BadNaine, and Bad- 
Value errors. 

To free colormap cells, use XFreeColors. 

XFxeeColors {display, colormap, pixels, npixels, planes) 
Display * display; 
Colormap colormap; 
unsigned long pixelsU; 
int npixels; 

unsigned long planes; 



display 


Specifies the connection to the XwiN server. 


colormap 


Specifies the colormap. 


pixels 


Specifies an array of pixel values that map to the cells in the 




specified colormap. 


npixels 


Specifies the number of pixels. 


planes 


Specifies the planes you want to free. 



The XFreeColors function frees the cells represented by pixels whose values 
are in the pixels array. The planes argument should not have any bits set to 1 
in common with any of the pixels. The set of all pixels is produced by ORing 
together subsets of the planes argument with the pixels. The request frees all of 
these pixels that were allocated by the client (using XAllocColor, XAlloc- 
NaraedColor, XAllocColorCells, and XZU.locColorPlanes). Note that freeing 
an individual pixel obtained from XAllocColorP lanes may not actually allow 
it to be reused until all of its related pixels are also freed. 

All specified pixels that are allocated by the client in the colormap are freed, 
even if one or more pixels produce an error. If a specified pixel is not a valid 
index into the colormap, a BadValue error results. If a specified pixel is not 
allocated by the chent (that is, is unallocated or is only allocated by another 
client), a BadAccess error results. If more than one pixel is in error, the one 
that gets reported is arbitrary. 

XFreeColors can generate BadAccess, BadColor, and BadValue errors. 
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Reading Entries in a Coiormap 

The XQueryColor and XQueryColors functions return the RGB values stored in 
the specified coiormap for the pixel value you pass in the pixel member of the 
XColor structure(s). The values returned for an tmallocated entry are 
undefined. These functions also set the flags member in the XColor structure to 
all three colors. If a pixel is not a valid index into the specified coiormap, a 
BadValue error results. If more than one pixel is in error, the one that gets 
reported is arbitrary. 

To query the RGB values of a single specified pixel value, use XQueryColor. 

XQueryColor {dispUnf, cdormap, defjnjmi) 
Display ^display; 
Coiormap cdormap; 
XColor *d^JnjMt; 

display Specifies the connection to the XwiN server. 

coiormap Specifies the coiormap. 

defjnj>ut Specifies and returns the RGB values for the pixel specified in 
the structure. 

The XQueryColor function returns the RGB values for each pixel in the XColor 
structures and sets the DoRed, DoGreen, and DoBlue flags. 

XQueryColor can generate BadColor and BadValue errors. 

To query the RGB values of an array of pixels stored in color structures, use 
XQueryColors. 

XQiiez:yColor8 {display, coiormap, defsjnjmt, ncolors) 
Display *display; 
Coiormap cdormap; 
XColor defsJnjmtU; 
int ncaiors; 

display Specifies the connection to the XwiN server. 

coiormap Specifies the coiormap. 
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defsjnjjut Specifies and returns an array of color definition structures for 
the pixel specified in the structure. 

ncolors Specifies the number of XColor structures in the color definition 

array. 

The XQueryColors function returns the RGB values for each pixel in the 
XColor structures and sets the DoRed, DoGreen, and DoBlue flags. 

XQueryColors can generate BadColor and BadValue errors. 
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Pixmaps can only be used on the screen on which they were created. Pixmaps 
are off-screen resources that are used for various operations, for example, 
defining cursors as tiling patterns or as the source for certain raster operations. 
Most graphics requests can operate either on a window or on a pixmap. A bit- 
map is a single bit-plane pixmap. 

To create a pixmap of a given size, use XCreatePixmap. 

Pixmiqp XCreatePixmap (<lis;'2ay, d, vndth, height, deffth) 
Display ^display; 
Drawable d; 

unsigned int width, height; 
unsigned int depth; 

display Specifies the connection to the XwiN server. 

d Specifies which screen the pixmap is created on. 

xvidth 

height Specify the width and height, which define the dimensions of 

the pixmap. 

depth Specifies the depth of the pixmap. 

The XCreatePixmap function creates a pixmap of the width, height, and depth 
you specified and returns a pixmap ID that identifies it. It is valid to pass an 
InputOnly window to the drawable argument. The width and height argu- 
ments must be nonzero, or a BadValue error results. The depth argument must 
be one of the depths supported by the screen of the specified drawable, or a 
BadValue error results. 

The server uses the specified drawable to determine on which screen to create 
the pixmap. The pixmap can be used only on this screen and only with other 
drawables of the same depth (see XCopyPlane for an exception to this rule). 
The initial contents of the pixmap are undefined. 

XCreatePixmap can generate BadAlloc, BadDrawable, and BadValue errors. 

To free all storage associated with a specified pixmap, use XFreePixmap. 

XFzetf ixmap {display, pixmap) 
Display ^display; 
Pixmap pixmap; 
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display Specifies the connection to the XwiN server. 

pixmap Specifies the pixmap. 

The XFreePixraap function first deletes the association between the pixmap ID 
and the pixnup. Then, the XwiN server frees the pixmap storage when there 
are no references to it. The pixmap should never be referenced again. 

XFreePixniap can generate a BadP jjonap error. 
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Most attributes of graphics operations are stored in Graphic Contexts (GCs). 
These include line width, line style, plane mask, foreground, background, tile, 
stipple, clipping region, end style, join style, and so on. Graphics operations 
(for example, drawing lines) use these values to determine the actual drawing 
operation. Extensions to X may add additional components to GCs. The con- 
tents of a GC are private to Xlib. 

Xlib implements a write-back cache for all elements of a GC that are not 
resource IDs to allow Xlib to implement the transparent coalescing of changes to 
GCs. For example, a call to XSetForeground of a GC followed by a call to 
XS^tLineAttributes results in only a single-change GC protocol request to the 
server. GCs are neither expected nor encouraged to be shared between chent 
applications, so this write-back caching should present no problems. Applica- 
tions cannot share GCs without external synchronization. Therefore, sharing 
GCs between applications is highly discouraged. 

To set an attribute of a GC, set the appropriate member of the XGCValues struc- 
ture and OR in the corresponding value bitmask in your subsequent calls to 
XCreateGC. The symbols for the value mask bits and the XGCValues structure 
are: 

/* GC attribute value mask bits */ 



#de£ine 


GCFunction 


(1L«0) 


#define 


GCPlanellBLsk 


(1L«1) 


#de£me 


OCFoiegxound 


(1L«2) 


#define 


GCBadcground 


(1L«3) 


#de£ine 


GCLinaWidth 


(1L«4) 


#define 


GCLineStyle 


(1L«5) 


#define 


G0Cap8tyl« 


(1L«6) 


#define 


GCJolnStyla 


(1L«7) 


#defme 


GCFillStyle 


(1L«8) 


#define 


GCFillRule 


(1L«9) 


#define 


GCTiltt 


(1L«10) 


#define 


GCStipple 


(1L«11) 


#define 


GCTiXeStipXDrigin 


(1L«12) 


#define 


GCTilttStipYDrigin 


(1L«13) 
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#define GCPont (1L«14) 

#defme GCSubwindowModa (1L«15) 

#defme GCGra^phicsExpomires (1L«16) 

#de£ine QCClipXDrigin (1L«17) 

#define OCClipYOrigin (1L«18) 

#defme GOClipHBLBk (1L«19) 

#defme GCDaBbO£faet (1L«20) 

#define GCDashList (1L«21) 

#define GCArcMode aL«22) 



/* Values */ 



typedef 8tz\2ct ( 

int function; /* 
unsigned long plane jnask; /* 
unsigned long f ozegzound; /* 
unsigned long background;/* 
int linejifidth; /* 
int line_style; /* 
int c^_style; /* 
int joinjityle; /* 
int fill_style; /* 
int fill_i:ule; /* 
int arcjnode; /* 
Pixma^ tile; /* 
Pixma^ stipple; /* 
int ts_xjorigin; /* 
int ts_yjorigin; 
Font font; 
int subwindoir node; 



logical operation */ 
plane mask */ 
foreground pixel */ 
background pixel */ 
line width (in pisosls) 



V 



LineSolid, LineOnOf fDash, LineDoubleDash */ 
C^qpNotLast, Ca^sButt, CapRound, C«^Projecting V 
JoinMiter, JoinRound, JoinBevel */ 

PillSolid, FillTiled, FillStippled FillOpaqueStippled*/ 

EvenOddRule, WindingRule */ 

ArcChord, ArcPieSlice */ 

tile pixmap for tiling operations */ 

stipple 1 plane pixmap for stippling */ 

offset for tile or stipple operations */ 



default text font for text operations */ 
ClipByChildren, Includelnferiors */ 
Bool graphics jsxposures; /* boolean, should exposures be generated */ 

origin for clipping */ 



int dip^xjorigin; 
int dip^jorigin; 
Pixmap dipjnask; 
int dashjoffset; 
char dashes; 
) XSCValues; 



/* 

/* 
/* 



bitmaqp clipping; other calls for rects */ 
patterned/dashed line information */ 
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The default GC values are: 



Component 



Default 



function 

plane_mask 

foreground 

background 

line_width 

line_style 

cap_style 

joinstyle 

fill_style 

fill__rule 

arc_mode 

tile 



stipple 
ts_x_origin 
ts_y_origin 
font 

subwindow_mode 

graphics_exposures 

clip_x_origin 

clip_y_origin 

clipjnask 

dash^offset 

dashes 



GXcx>py 

All ones 

0 

1 

0 

LineSolid 

CapButt 

JoinMiter 

FillSolid 

EvenOddRule 

ArcPieSlice 

Pixmap of unspecified size filled with foreground pixel 

(that is, client specified pixel if any, else 0) 

(subsequent changes to foreground do not affect this pixmap) 

Pixmap of unspecified size filled with ones 

0 

0 

<implementation dependent> 

ClipByChildren 

True 

0 

0 

None 
0 

4 (that is, the list [4, 4]) 



Note that foreground and background are not set to any values likely to be use- 
ful in a window. 
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The function attributes of a GC are used when you update a section of a draw- 
able (the destination) with bits from somewhere else (the source). The function 
in a GC defines how the new destination bits are to be computed from the 
source bits and the old destination bits. GXcopy is typically the most useful 
because it will work on a color display, but special applications may use other 
functions, particularly in concert with particular planes of a color display. The 
16 GC functions, defined in < Xll/X.h >, are: 



Function Name 


Hex Code 


Operation 


QCclear 


Uxu 


U 


GXanCL 


UXi 


SrC AINL' uSt 


GXaundReverse 


0x2 


src AND NOT dst 


QCcopy 


0x3 


src 


GXandlnverted 


0x4 


(NOT src) AND dst 


GXnoop 


0x5 


dst 


GXKor 


0x6 


wc XOR dst 


GXor 


0x7 


src OR dst 


GXnor 


0x8 


(NOT src) AND (NOT dst) 


GXequiv 


0x9 


(NOT src) XOR dst 


GXinvert 


Oxa 


NOT dst 


GXorReverse 


Oxb 


src OR (NOT dst) 


GXcopylnverted 


Oxc 


NOT src 


GXbrlnverted 


Oxd 


(NOT src) OR dst 


GXnand 


Oxe 


(NOT src) OR (NOT dst) 


GXset 


Oxf 


1 



Many graphics operations depend on either pixel values or planes in a GC. The 
planes attribute is of type long, and it specifies which planes of the destination 
are to be modified, one bit per plane. 

A monochrome display has only one plane and will be the least-significant bit 
of the word. As planes are added to the display hardware, they will occupy 
more significant bits in the plane mask. 
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In graphics operations, given a source and destination pixel, the result is com- 
puted bitwise on corresponding bits of the pixels. That is, a Boolean operation 
is performed in each bit plane. The plane_mask restricts the operation to a sub- 
set of planes. A macro constant AllPlanes can be used to refer to all planes of 
the screen simultaneously. The result is computed by the following: 

((src FUNC dst) AND plane-mask) OR (dst AND (NOT plane-mask)) 

Range checking is not performed on the values for foreground, background, or 
plane__mask. They are simply truncated to the appropriate number of bits. The 
line-width is measured in pixels and either can be greater than or equal to one 
(wide line) or can be the special value zero (thin line). 

Wide lines are drawn centered on the path described by the graphics request. 
Unless otherwise specified by the join-style or cap-style, the bounding box of a 
wide line with endpoints [xl, yl], [x2, y2] and width w is a rectangle with ver- 
tices at the following real coordinates: 

[xl-(w*8n/2), yl+(w*cs/2)], [xl+ (w*sn/2) , yl-(w*ca/2) 
[x2-(w*sn/2), y2+(w*cs/2)], [x2+ (w*sn/2) , y2-(w*cs/2)] 

Here sn is the sine of the angle of the line, and cs is the cosine of the angle of 
the line. A pixel is part of the line and so is drawn if the center of the pixel is 
fully inside the bounding box (which is viewed as having infinitely thin edges). 
If the center of the pixel is exactly on the bounding box, it is part of the line if 
and only if the interior is immediately to its right (x increasing direction). Pixels 
with centers on a horizontal edge are a special case and are part of the line if 
and only if the interior or the boundary is immediately below (y increasing 
direction) and the interior or the boundary is immediately to the right (x 
increasing direction). 

Thin lines (zero line-width) are one-pixel-wide lines drawn using an unspecified, 
device-dependent algorithm. There are only two constraints on this algorithm. 

1. If a line is drawn undipped from [xl,yl] to [x2,y2] and if another line is 
drawn undipped from [xl-Kix,yl+dy] to [x2-fdx,y2+dy], a point [x,y] is 
touched by drawing the first line if and only if the point [x+dx,y+dy] is 
touched by drawing the second line. 

2. The effective set of points comprising a line cannot be affected by clip- 
ping. That is, a point is touched in a clipped line if and only if the point 
lies inside the clipping region and the point would be touched by the line 
when drawn undipped. 
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A wide line drawn from [xl,yl] to [x2,y2] always draws the same pixels as a 
wide line drawn from [x2,y2] to [xl,yl], not counting cap-style and join-style. It 
is recommended that this property be true for thin lines, but this is not required. 
A line-width of zero may differ from a line-width of one in which pixels are 
drawn. This permits the use of many manufacturers' line drawing hardware, 
which may run many times faster than the more precisely specified wide lines. 

In general, drawing a thin line will be faster than drawing a wide line of width 
one. However, because of their different drawing algorithms, thin lines may not 
mix well aesthetically with wide lines. If it is desirable to obtain precise and 
uniform results across all displays, a client should always use a line-width of 
one rather than a line-width of zero. 

The line-style defines which sections of a line are drawn: 

LineSolid The full path of the line is drawn. 

LineDoubleDash The full path of the line is drawn, but the even dashes are fOled dif- 
ferently than the odd dashes (see fill-style) with CapButt style used 
vfhere even and odd dashes meet. 

LineOnOffDash Only the even dashes are drawn, and cap-style applies to all internal 

ends of the individual dashes, except CaqpHotLast is treated as Cap- 
Butt. 

The cap-style defines how the endpoints of a path are drawn: 

Ci^ot:La8t This is equivalent to Cs^iButt except that for a line-width of zero the 

final endpoint is not drawn. 

CapButt The line is square at the endpoint (perpendicular to the slope of the 

Une) with no projection beyond. 

CiqpRound The line has a circular arc with the diameter equal to the line-width, 

centered on the endpoint. (This is equivalent to C«^Butt for line- 
width of zero). 

CapPro jecting The line is square at the end, but the path continues beyond the end- 

point for a distance equal to half the line-width. (This is equivalent 
to CapButt for line-width of zero). 
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The join-style defines how comers are drawn for wide lines: 

JoinMlter The outer edges of two lines extend to meet at an angle. However, if 

tiie angle is less than 11 degrees, then a JoinBeval join-style is used 
instead. 



JoinRound 



JoinBevel 



The comer is a circular arc with the diameter equal to the line- width, 
centered on the jc^point 

The comer has CapButt endpoint styles with the triangular notch 
fOled. 



For a line with coincident endpoints (xl=x2, yl=y2), when the cap-style is 
applied to both endpoints, the semantics depends on the line-width and the 

cap-style: 

CapNotLast thin The results are device-dependent, but the desired effect is 

that nothing is drawn. 

CapButt thin The results are device-dependent, but the desired effect is 

that a single pixel is drawn. 

CapRound thin The results are the same as for CapButt /thin. 

Ci^ro jaoting thin The results are the same as for Butt /thin. 

CapButt wide Nothing is drawn. 

CapRound wide The dosed path is a circle, centered at the endpoint, and 

with the diameter equal to the line-width. 

Ci^ro jecting wide The dosed path is a square, aligned with the coordinate 

axes, centered at the endpoint, and with the sides equal to 
the line-width. 



For a line with coincident endpoints (xl=x2, yl=y2), when the join-style is 
applied at one or both endpoints, the effect is as if the line was removed from 
the overall path. However, if the total path consists of or is reduced to a single 
point joined with itself, the effect is the same as when the cap-style is applied at 
both endipoints. 

The tile/stipple and clip origins are interpreted relative to the origin of what- 
ever destination drawable is specified in a graphics request. The tile pixmap 
must have the same root and depth as the GC, or a BadMatch error results. The 
stipple pixmap must have depth one and must have the same root as the GC, or 
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a BadMatch error results. For stipple operations where the fill-style is 
FillStippled but not FillOpaqueStippled, the stipple pattern is tiled in a 
single plane and acts as an additional clip mask to be ANDed with the clip- 
mask. Although some sizes may be faster to use than others, any size pixmap 
can be used for tiling or stippling. 

The fill-style defines the contents of the source for line, text, and fill requests. 
For all text and fill requests (for example, XDrawText, XDrawTextl6, XFillRec- 
tangle, XFillPolygon, and XFillArc); for line requests with line-style 
LineSolid (for example, XDrawLine, XDrawSegments, XDrawRect angle, 
XDrawArc); and for the even dashes for line requests with line-style LineOnOf f- 
Dash or LineDoubleDash, the following apply: 

FillSolld Foreground 
FillTiled Tile 

FillOpaqueStippled A tile with the same width and height as stip- 
ple, but with background everywhere stipple 
has a zero and with foreground everywhere 
stipple has a one 

FillStippled Foreground masked by stipple 

When drawing lines with line-style LineDoubleDash, the odd dashes are con- 
trolled by the fill-style in the following manner: 

FillSolid Background 

FillTiled Same as for even dashes 

FillOpaqueStippled Same as for even dashes 

FillStippled Background masked by stipple 

Storing a pixmap in a GC might or might not result in a copy being made. If 
the pixmap is later used as the destination for a graphics request, the change 
might or might not be reflected in the GC. If the pixmap is used simultaneously 
in a graphics request both as a destination and as a tile or stipple, the results are 
undefined. 
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For optimum perforinance, you should draw as much as possible with the same 
GC (without changing its components). The costs of changing GC components 
relative to using different GCs depend upon the display hardware and the 
server implementation. It is quite likely that some amount of GC information 
will be cached in display hardware and that such hardware can only cache a 
small number of GCs. 

The dashes value is actually a simplified form of the more general patterns that 
can be set with XSetDashes. Specifying a value of N is equivalent to specifying 
the two-element hst [N, N] in XSetDashes. The value must be nonzero, or a 
BadValue error results. 

The clip-mask restricts writes to the destination drawable. If the clip-mask is set 
to a pixmap, it must have depth one and have the same root as the GC, or a 
BadMatch error results. If clip-mask is set to None, the pixels are always drawn 
regardless of the dip origin. The clip-mask also can be set by calling the 
XSetClipRectangles or XSetRegion functions. Only pixels where the clip- 
mask has a bit set to 1 are drawn. Pixels are not drawn outside the area 
covered by the clip-mask or where the dip-mask has a bit set to 0. The dip- 
mask affects all graphics requests. The clip-mask does not dip sources. The 
clip-mask origin is interpreted relative to tfie origin of whatever destination 
drawable is specified in a graphics request. 

You can set the subwindow-mode to ClipByChildren or Includeinf triors. 
For ClipByChildren, both source and destination windows are additionally 
clipped by all viewable InputOutput children. For Includelnferiors, neither 
source nor destination window is dipped by inferiors. This will result in 
including subwindow contents in the source and drawing through subwindow 
boundaries of the destination. The use of Includeinf eriors on a window of 
one depth with mapped inferiors of differing depth is not illegal, but the seman- 
tics are undefined by the core protocol. 

The fill-rule defines what pixels are inside (drawn) for paths given in 
XFillPolygon requests and can be set to EvenOddRule or WindingRule. For 
EvenOddRule, a point is inside if an infinite ray with the point as origin crosses 
the path an odd number of times. For WindingRule, a point is inside if an 
infinite ray with the point as origin crosses an unequal number of clockwise and 
counterclockwise directed path segments. A dockwise directed path segment is 
one that crosses the ray from left to right as observed from the point. A coun- 
terclockwise segment is one that crosses the ray from right to left as observed 
from the point. The case where a directed line segment is coincident with the 
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ray is uninteresting because you can simply choose a different ray that is not 
coincident with a segment 

For both EvenOddRule and WindingRule, a point is infinitely small, and the 
path is an infinitely thin line. A pixel is inside if the center point of the pixel is 
inside and the center point is not on the boundary. If the center point is on the 
boundary, the pixel is inside if and only if the polygon interior is immediately 
to its rig^t (x increasing direction). Pixels with centers on a horizontal edge are 
a special case and are inside if and only if the polygon interior is immediately 
below (y increasing direction). 

The arc-mode controls filling in the XFillArcs function and can be set to 
ArcPieSlice or ArcChord. For ArcPieSlice, the arcs are pie-slice filled. For 
ArcChord, the arcs are chord filled. 

The graphics-exposure flag controls GraphicsEapose event generation for 
XCopyArea and XCopyPlane requests (and any similar requests defined by 
extensions). 

To create a new GC that is usable on a given screen with a depth of drawable, 
use XCreateGC. 



GO yCr99teQCi display, d, vtdvemask, values) 
Display *display; 
Drawable d; 

unsigned long valuemask; 
XGCValues *v(dues; 



display Specifies the connection to the XwiN server. 

d Specifies the drawable. 

valuemask Specifies which components in the GC are to be set using the 
information in the specified values structure. This argument is 
the bitwise inclusive OR of one or more of the valid GC com- 
ponent mask bits. 

values Specifies any values as specified by the valuemask. 



The XCreateGC function creates a graphics context and returns a GC. The GC 
can be used with any destination drawable having the same root and depth as 
the specified drawable. Use with other drawables results in a BadMatch error. 
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XCreateGC can generate BadAlloc, BadDrawable, BadFont, BadMatch, BadPix- 
map, and BadValue errors. 

To copy components from a source GC to a destination GC, use XCopyGC. 

XCopyGC (<lisp2ay, src, vdumask, dest) 
Display ^display; 
GC src, dest; 

unsigned long valuemask; 

display Specifies the connection to the XwiN server. 

src Specifies the components of the source GC. 

valuemask Specifies which components in the GC are to be copied to the 
destination GC. This argument is the bitwise inclusive OR of 
one or more of the valid GC component mask bits. 

dest Specifies the destination GC. 

The XCopyGC function copies the specified components from the source GC to 
the destination GC. The source and destination GCs must have the same root 
and depth, or a BadMatch error results. The valuemask specifies which com- 
ponent to copy, as for XCreateGC. 

XCopyGC can generate BadAlloc, BadGC, and BadMatch errors. 

To change the components in a given GC, use XChangeGC. 

XChangeGC {display, gc, valueinask, values) 
£>isplay ^display; 
GCgc; 

unsigned long valuemask; 
XGCValues *values; 

display Specifies the connection to the XwiN server. 

gc Specifies the GC. 

valuemask Specifies which components in the GC are to be changed using 
information in the specified values structure. This argument is 
the bitwise inclusive OR of one or more of the valid GC com- 
ponent mask bits. 
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values Specifies any values as specified by the valuemask. 

The XChangeGC function changes the components specified by valuemask for the 
specified GC. The values argument contains the values to be set. The values 
and restrictions are the same as for XCreateGC. Changing the clip-mask over- 
rides any previous XSetClipRectangles request on the context. Changing the 
dash-offset or dash-list overrides any previous XSetDashes request on the con- 
text. The order in which components are verified and altered is server- 
dependent. If an error is generated, a subset of the components may have been 
altered. 

XChangeGC can generate BadAlloc, BadFont, BadGC, BadMatch, BadPixrnap, 
and BadValue errors. 

To free a given GC, use XFreeGC. 

XFre«GC (display, gc) 
Display ^display; 
GC gc; 

display Specifies the connection to the XwiN server. 

gc Specifies the GC. 

The XFreeGC function destroys the specified GC as well as all the associated 
storage. 

XFreeGC can generate a BadGC error. 

To obtain the GContext resource ID for a given GC, use XGContextFrcxtiGC. 

GCmtext XGContextFromOC (gc) 
GC gc; 

gc Specifies the GC for which you want the resource ID. 
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This section discusses how to set the: 

■ Foreground, background, plane mask, or function components 

■ Line attributes and dashes components 

■ Fill style and fill rule components 

■ Fill tile and stipple components 

■ Font component 

■ Clip region component 

■ Arc mode, subwindow mode, and graphics exposure components 

Setting the Foreground, Baclcground, Function, or 
Plane Masic 

To set the foreground, background, plane mask, and function components for a 
given GC, use XSetState. 

XSetStattt (dispUtif, gc, foreground, background, function, plane jmsk) 
Display *disphy; 
CCgc; 

unsigned long foreground, background; 
int function; 

unsigned Icmg plane jnask; 

display Specifies the connection to the XwiN server. 

gc Specifies the GC- 

foreground Specifies the foreground you want to set for the specified GC. 

background Specifies the background^ you want to set for the specified GC. 

function Specifies the function you want to set for the specified GC. 

plane jnask Specifies the plane mask. 

XSetState can generate BadAlloc, BadGC, and BadValue errors. 
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To set the foreground of a given GC, use XSetForeground. 

XSetFor^gramd {display, gc, foreground) 
Display ^display; 
GCgc; 

unsigned long foreground; 

display Specifies the connection to the XWIN server. 

gc Specifies the GC. 

foreground Specifies the foreground you want to set for the specified GC. 

XSetForeground can generate BadAlloc and BadGC errors. 

To set the background of a given GC, use XSetBackground. 

XSetBac]cground(its;72ay, gc, background) 
Display *display; 
GCgc; 

unsigned long background; 

display Specifies the connection to the XwiN server. 

gc Specifies the GC. 

background Specifies the background you want to set for the specified GC. 

XSetBackground can generate BadAlloc and BadGC errors. 

To set the display function in a given GC, use XSetFunction. 

XSetFunction (^ispky, gc, function) 
Display *display; 
GCgc; 
int function; 

display Specifies the connection to the XwiN server. 

gc Specifies the GC. 

function Specifies the function you want to set for the specified GC. 
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XSetFunction can generate BadAlloc, BadGC, and BadValue errors. 
To set the plane mask of a given GC, use XSetPlaneMask. 

XSetPlaneMask {display, gc, plane jnask) 
Display ^display; 

CCgc; 

unsigned long pianejnask; 

display Spedfies the <x)nnection to the XwiN server. 

gc Specifies the GC. 

plane jnask Specifies the plane mask. 

XSetPlaneMask can generate BadAlloc and BadGC errors. 

Setting the Line Attributes and Dasiies 

To set the line drawing components of a given GC, use XSetLineAttributes. 

XSetLineAttributes (display, gc, linejoidth, Ivm^styU, cap_style, joinjtyle) 
Display ^display; 
CCgc; 

unsigned int linejoidth; 
int line^siyle} 
int capjtyU; 
int join_style; 



display Spedfies the connection to the XwiN server. 

gc Spedfies the GC. 

linejmdth Spedfies the line-width you want to set for the spedfied GC. 

linejtyle Spedfies the line-style you want to set for the specified GC. 

You can pass LineSolid, LineOnOf £Dash, or LineDoubleDash. 

capjtyle Spedfies the line-style and cap-style you want to set for the 

specified GC. You can pass CapNotLast, CapButt, CapRoimd, 
or CapPro jectlng. 
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join_style Specifies the line join-style you want to set for the specified GC. 
You can pass JoinMiter, JoinRound, or JoinBevel. 

XSetLineAttributes can generate BadAlloc, BadGC, and BadValue errors. 

To set the dash-offset and dash-list for dashed line styles of a given CQ use 
XSetDashes. 



{displaj/, gc, dashjtffset, daskjist, n) 
Display *displtnf; 
GCgc; 

int dash jjffset; 
char dashJktW', 
int n; 

display Specifies the connection to the XWIN server. 

gc Specifies the GC. 

dashj)ffset Specifies the phase of the pattern for the dashed line-style you 
want to set for the specified GC. 

dashjist Specifies the dash-list for the dashed line-style you want to set 

for the specified GC. 

n Specifies the number of elements in dash_list. 

The XSetDashes function sets the dash-offset and dash-list attributes for dashed 
line styles in the specified GC. There must be at least one element in the 
specified dashjist, or a BadValue error results. The initial and alternating ele- 
ments (second, fourth, and so on) of the dashjist are the even dashes, and the 
others are the odd dashes. Each element specifies a dash length in pixels. All 
of the elements must be nonzero, or a BadValue error results. Specifying an 
odd-length list is equivalent to specifying the same list concatenated with itself 
to produce an even-length list. 

The dash-offset defines the phase of the pattern, specifying how many pixels 
into the dash-list the pattern should actually begin in any single graphics 
request. Dashing is continuous through path elements combined with a join- 
style but is reset to the dash-offset each time a cap-style is applied at a line end- 
point. 
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The unit of measure for dashes is the same for the ordinary coordinate system. 
Ideally, a dash length is measured along the slope of the line, but implementa- 
tions are only required to match this ideal for horizontal and vertical lines. Fail- 
ing the ideal semantics, it is suggested that the length be measured along the 
major axis of the line. The major axis is defined as the x axis for lines drawn at 
an angle of between -45 and +45 degrees or between 315 and 225 degrees from 
the X axis. For all other lines, the major axis is the y axis. 

XSetDashes can generate BadAlloc, BadGC, and BadValue errors. 



Setting the Fill Style and Fill Rule 

To set the fill-style of a given GC, use XSetFillStyle. 

XSetFillStyle {display, gc, fUljh/le) 
Display *display; 
GCgc; 
int fiUjtyle; 

Specifies the connection to the XwiN server. 
Specifies the GC. 

Specifies the fill-style you want to set for the specified GC. You 
can pass FillSolid, FillTiled, FillStippled, or 
FillppaqueStippled. 

XSetFillStyle can generate BadAlloc, BadGC, and BadValue errors. 
To set the fill-rule of a given GC, use XSetFillRule. 

XSetFillBule (display, gc, filljide) 
Display ^display; 
GCgc; 
M filljide; 

display Specifies the connection to the XwiN server. 

gc Specifies the GC. 



display 
filljtyle 
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filljule Specifies the fill-rule you want to set for the specified GC. You 

can pass EvenOddRule or WindingRule. 

XSetFillRule can generate BadAlloc, BadGC, and BadValue errors. 



Setting the Fill Tile and Stipple 

Some displays have hardware support for tiling or stippling with patterns of 
specific sizes. Tiling and stippling operations that restrict themselves to those 
specific sizes run much faster than such operations with arbitrary size pattems. 
Xlib provides functions that you can use to determine the best size, tile, or stip- 
ple for the display as well as to set the tile or stipple shape and the tile or stip- 
ple origin. 

To obtain the best size of a tile, stipple, or cursor, use XQueryBestSize. 

status XCXieryBestSize {display, doss, which jcreen, width, height, width jetum, height jetum) 
Display ^display; 
int doss; 

Drawable xMchjcreen; 

unsigned int width, height; 

unsigned int *widthjretum, *heightjretum; 

display Specifies the connection to the XwiN server. 

class Specifies the class that you are interested in. You can pass 

TileShape, CursorShape, or StippleShape. 

which_screen Specifies any drawable on the screen. 

xvidth 

height Specify the width and height. 

width^retum 

height jetum Return the width and height of the object best supported by the 
display hardware. 
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The XQueryBestSize function returns the best or closest size to the specified 
size. For CursorShape, this is the largest size that can be fully displayed on the 
screen specified by which_screen. For TileShape, this is the size ttiat can be 
tiled fastest. For StippleShape, this is the size that can be stippled fastest. For 
CursorShape, the drawable indicates the desired screen. For TileShape and 
StippleShape, the drawable indicates the screen and possibly the window dass 
and depth. An inputOnly window cannot be used as the drawable for 
TileShape or StippleShape, or a BadMatch error results. 

XQueryBestSize can generate BadDrawable, BadMatch, and BadValue errors. 

To obtain the best fill tile shape, use XQueryBestTile. 

status XQuaryBestTile {display, which jcreen, width, height, width jetum, height jetum) 
Display *disphiy; 
Drawable xohidi jcreen; 
unsigned int width, height; 
unsigned int *width_retum, *heightjretum; 

display Specifies the connection to the XwiN server. 

which_screen Specifies any drawable on the screen. 
uridth 

height Specify the width and height 

widthj'eturn 

hd^tjreturn Return the width and height of the object best supported by the 
display hardware. 

The XQueryBestTile function returns the best or closest size, that is, the size 
that can be tiled fastest on the screen specified by which^screen. The drawable 
indicates the screen and possibly the window class and depth. If an InputOnly 
window is used as the drawable, a BadMatch error results. 

XQueryBestTile can generate BadDrawable and BadMatch errors. 

To obtain the best stipple shape, use XQueryBest Stipple. 
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status XQuttxyBoatStipplo (<itsplkiy, which^screen, width, height, width jetum, heightjretum) 
Display ^display, 
Drawable which _screen) 
unsigned int width, height; 
unsigned int *widthjretum, *heightj^etum; 



display Specifies the connection to the XwiN server. 

which jcreen Specifies any drawable on the screen, 
width 

height Specify the width and height. 



widthjetum 

height jretum Return the width and height of the object best supported by the 
display hardware. 

The XQueryBestStipple function returns the best or closest size, that is, the 
size that can be stippled fastest on the screen specified by which_screen. The 
drawable indicates the screen and possibly the window class and depth. If an 
InputOnly window is used as the drawable, a BadMatch error results. 

XQueryBestStipple can generate BadDrawable and BadMatch errors. 

To set the fill tile of a given GC, use XSetTile. 

XStttTiltt {display, gc, tile) 
Display *display; 
GCgc; 
Pixmap tHe; 

display Specifies the connection to the XwiN server. 

gc Specifies the GC. 

tile Specifies the fill tile you want to set for the specified GC. 

The tile and GC must have the same depth, or a BadMatch error results. 
XSetTile can generate BadAlloc, BadGC, BadMatch, and BadPixxnap errors. 
To set the stipple of a given GC, use XSetStipple. 
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XSetStipple {display, gc, stipple) 
Display *dispUaf; 
CCgc; 

Pixmap stipple; 

display Specifies the connection to the XwiN server. 

gc Specifies the GC. 

stipple Specifies the stipple you want to set for the specified GC. 

The stipple and GC must have the sante depth, or a BadM^tch error results. 
XSetStipple can generate BadAlloc, BadGC, BadMatch, and BadPixinap errors. 
To set the tile or stipple origin of a given GC, use XSetTSOrlgln. 

XSatTSOrigin(dtsptey,^c, tsjcyrigin, tsjfjmgin) 
Display ^display; 
CCgc; 

int tsjcjmgin, tsjfjmgin; 



display Specifies the connection to the XwiN server. 

gc Specifies the GC. 

tsjcj)rigin 

tsj/j)rigin Specify the x and y coordinates of the tile and stipple origin. 



When graphics requests call for tiling or stippling, the parent's origin will be 
interpreted relative to whatever destination drawable is specified in the graphics 
request. 

XSetTSOrigin can generate BadAlloc and BadGC error. 
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Setting the Current Font 

To set the current font of a given GC, use XSetFont. 

XSetFont {displm/, gc, font) 
Display *dispUnf; 
GC gc; 
Font font; 

display Specifies the connection to the XwiN server. 

gc Specifies the GC 

font Specifies the font. 

XSetFont can generate BadAlloc, BadFont, and BadGC errors. 

Setting tlie Ciip Region 

Xlib provides functions that you can use to set the clip-origin and the clip-mask 
or set the clip-mask to a list of rectangles. 

To set the clip-origin of a given GQ use XSetClipOrigin. 

XSetClipOrigin(<lisp%, gc, cUpjcj)rigin, dipjfjmgin) 
Display ^display; 
GQgc; 

int dipjcjorigin, clipjfjmgin; 



display Specifies the connection to the XwiN server. 

gc Specifies the GC. 

clipxorigin 

clipj/_origin Specify the x and y coordinates of the clip-mask origin. 



The clip-mask origin is interpreted relative to the origin of whatever destination 
drawable is specified in the graphics request 
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XSetClipOrigin can generate BadAlloc and BadGC errors. 

To set the clip-mask of a given GC to the specified pixmap, use XSetClipMask. 

XSetClipMftsk {display, gc, pixmap) 
Display ^display; 
GCgc; 

Pixmap pixmap; 

display Specifies the connection to the XwiN server. 

gc Specifies the GC. 

pixmap Specifies the pixmap or None. 

If the clip-mask is set to None, the pixels are are always drawn (regardless of 
the clip-origin). 

XSetClipMask can generate BadAlloc, BadGC, BadMatch, and BadValue errors. 

To set the clip-mask of a given GC to the specified list of rectangles, use 
XSetClipRectangles . 

XSetClipRectangles {display, gc, clipjcjmgin, clip_yjmgin, rectangles, n, ordering) 
Display ^display; 
GCgc; 

int clipjcjmgin, clipjfjmgin; 
XRectangle rectanglesU; 
int n; 

int ordering; 



display Specifies the connection to the XwiN server. 

gc Specifies the GC. 

clipjc_origin 

clipj/j)rigin Specify the x and y coordinates of the clip-mask origin. 

rectangles Specifies an array of rectangles that define the clip-mask. 

n Specifies the number of rectangles. 

ordering Specifies the ordering relations on the rectangles. You can pass 



Unsorted, YSorted, YXSorted, or YXBanded. 
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The XSetClipRectangles function changes the dip-mask in the specified GC to 
the specified list of rectangles and sets the dip origin. The output is clipped to 
remain contained within the rectangles. The dip-origin is interpreted relative to 
the origin of whatever destination drawable is spedfied in a graphics request. 
The rectangle coordinates are interpreted relative to the clip-origin. The rectan- 
gles should be nonintersecting^ or the graphics results will be undefined. Note 
that the list of rectangles can be empty, which effectively disables output. This 
is the opposite of passing None as the clip-mask in XCreateGC, XChangeGC, and 
XSetClipMask. 

If known by the client, ordering relations on the rectangles can be specified with 
the ordering argument. This may provide faster operation by the server. If an 
incorrect ordering is spedfied, the XwiN server may generate a BadMatch error, 
but it is not required to do so. If no error is generated, the graphics results are 
undefined. Unsorted means the rectangles are in arbitrary order. YSorted 
means that the rectangles are nondecreasing in their Y origin. YXSorted addi- 
tionally constrains YSorted order in that all rectangles with an equal Y origin 
are nondecreasing in their X origin. YXBanded additionally constrains YXSorted 
by requiring that, for every possible Y scanline, all rectangles that indude that 
scanline have an identical Y origins and Y extents. 

XSetClipRectangles can generate BadAlloc, BadGC, BadMatch, and BadValue 
errors. 

Xlib provides a set of basic functions for performing region arithmetic. For 
information about these functions, see Chapter 10. 



Setting the Arc Mode, Subwindow Mode, and 
Graphics Exposure 

To set the arc mode of a given GC, use XSetAxcMcxie. 

XSatArcMode {display, gc, arcjnode) 
Display ^display; 
GCgc; 
int arcjnode; 
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display Specifies the connection to the XwiN server. 

gc Specifies the GC. 

arcjnode Specifies the arc mode. You can pass ArcChord or 

ArcPieSlice. 

XSetj^cMode can generate BadAlloc, BadGC, and BadValue errors. 
To set the subwindow mode of a given GC, use XSetSubwindowMode. 

XSetSubwindowMode {display, gc, svbwindawjnode) 
Display ^display; 
CCgc; 

int subwindawjnode; 

display Specifies the connection to the XwiN server. 

gc Specifies the GC. 

subxvindowjnode Specifies the subwindow mode. You can pass ClipByChil- 
dren or Includelnferiors. 

XSetSubwindowMode can generate BadAlloc, BadGC, and BadValue errors. 

To set the graphics-exposures flag of a given GC, use XSetGraphicsExposures. 

XSetGraphicaBxposures {display, gc, graphics exposures) 
Display ^display; 
CCgc; 

Bool graphics jxposures; 

display Specifies the connection to the XwiN server. 

gc Specifies the GC. 

gxaphks jxposures Specifies a Boolean value that indicates whether you want 
GraphicsExpose and NoExpose events to be reported when 
calling XCopyArea and XCopyPlane with this GC. 

XSetGraphicsExpo9ures can generate BadAlloc, BadGC, and BadValue errors. 
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Introduction 



Once you have connected the display to the XwiN server, you can use the Xlib 
graphics functions to: 

■ Clear and copy areas 

■ Draw points, lines, rectangles, and arcs 

■ Fill areas 

■ Manipulate fonts 

■ Draw text 

■ Transfer images between clients and the server 

■ Manipulate cursors 

If the same drawable and GC is used for each call, Xlib batches back-to-back 
calls to XDrawPoint, XDrawLine, XDrawRectangle, XFillArc, and XFillRec- 
tangle. Note that this reduces the total number of requests sent to the server. 
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Xlib provides functions that you can use to clear an area or the entire window. 
Because pixmaps do not have defined backgrounds, they cannot be filled by 
using the functions described in this section. Instead, to accomplish an analo- 
gous operation on a pixnnap, you should use XFillRectangle, which sets the 
pixmap to a known value. 

To clear a rectangular area of a given window, use XClearArea. 

XClAarAna (<2isp2^, w, x, y, width, height, exposures) 
Display ^display; 
Window w; 
int X, y; 

unsigned int width, height; 
Bool exposures; 



display 


Specifies the connection to the XwiN server. 


XV 


Specifies the window. 


X 

y 


Specify the x and y coordinates, which are relative to the origin 




of the window and specify the upper-left comer of the rectangle. 


width 




height 


Specify the width and height, which are the dimensions of the 




rectangle. 


exposures 


Specifies a Boolean value that indicates if Expose events are to 




be generated. 



The XClearArea function paints a rectangular area in the specified window 
according to the specified dimensions with the window's background pixel or 
pixmap. The subwindow-mode effectively is ClipByChildren. If width is zero, 
it is replaced with the current width of the window minus x. If height is zero, it 
is replaced with the current height of the window minus y. If the window has a 
defined background tile, the rectangle dipped by any children is filled with this 
tile. If the window has background None, the contents of the window are not 
changed. In either case, if exposures is True, one or more E^^se events are 
generated for regions of the rectangle that are either visible or are being 
retained in a backing store. If you specify a window whose class is InputOnly, 
a BadMatch error results. 
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XClearArea can generate BadMatch, BadValiie, and BadWindow errors. 

To dear the entire area in a given window, use XClearWindow. 

XCleazWindow ( display, w) 
Display '^display; 
Window w; 

display Specifies the connection to the XwiN server. 

w Specifies the window. 

The XClearWindow function clears the entire area in the specified window and 
is equivalent to XClearArea (display, w, 0, 0, 0, 0, False). If the window has a 
defined background tile, the rectan^e is tiled with a plane-mask of all ones and 
GXcopy function. If the window has background None, the contents of the win- 
dow are not changed. If you specify a window whose dass is InputOnly, a Bad- 
Match error results. 

XClearWindow can generate BadMatdi and BadWindow errors. 
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Xlib provides functions that you can use to copy an area or a bit plane. 

To copy an area between drawables of the same root and depth, use XCopyArea. 

XCopyArea {display, src, dest, gc, srcjc, srcjf, width, height, destjc, destjf) 
Display ^display; 
Drawable src, dest; 
GCgc; 

int STCjc, srcjy; 
tmsigned int width, height; 
int destjc, destjf; 

Specifies the connection to the XwiN server. 

Specify the source and destination rectangles to be combined. 
Specifies the GC 

Specify the x and y coordinates, which are relative to the origin 
of the source rectangle and specify its upper-left comer. 

Specify the width and height, which are the dimensions of both 
the source and destination rectangles. 

Specify the x and y coordinates, which are relative to the origin 
of the destination rectangle and specify its upper-left comer. 

The yCopykcea function combines the specified rectangle of src with the 
specified rectangle of dest. The drawables must have the same root and depth, 
or a BadMatch error results. 

If regions of the source rectangle are obscured and have not been retained in 
backing store or if regions outside the boundaries of the source drawable are 
specified, those regions are not copied. Instead, the following occurs on all 
corresponding destination regions that are either visible or are retained in back- 
ing store. If the destination is a window with a background other than None, 
corresponding regions of the destination are tiled with that background (with 
plane-mask of all ones and GXcopy function). Regardless of tiling or whether 
the destination is a window or a pixmap, if graphics-exposures is True, then 
GraphicsExpose events for all corresponding destination regions are generated. 



display 

src 
dest 

gc 

srcjc 
srcjy 

width 
height 

destjc 
destjf 
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If graphics-exposures is True but no GraphicsEjqpose events are generated, a 
NoExpose event is generated. Note that by default graphics-exposures is True 
in new GCs. 

This function uses these GC components: function, plane-mask, subwindow- 
mode, graphics-exposures, clip-x-origin, clip-y-origin, and clip-mask. 

XCopyArea can generate BadDrawable, BadGC, and BadMatch errors. 

To copy a single bit plane of a given drawable, use XCopyPlane. 

XCc^yPlane {display, src, dest, gc, srcjc, srcjf, width, height, destjc, destjf, plane) 
Display *display; 
Drawable src, dest; 
GC gc; 

int srcjc, srcjf; 
imsigned int zoidth, height; 
int destjc, destjf; 
unsigned long plane; 

display Specifies the connection to the XwiN server. 

src 

dest Specify the source and destination rectangles to be combined. 

gc Specifies the GC. 

srcjc 

src J/ Specify the x and y coordinates, which are relative to the origin 

of the source rectangle and specify its upper-left comer. 

xvidth 

height Specify the width and height, which are the dimensions of both 

the source and destination rectangles. 

destjx 

dest J/ Specify the x and y coordinates, which are relative to the origin 

of the destination rectangle and specify its upper-left comer. 

plane Specifies the bit plane. You must set exactly one bit to 1. 

The XCopyPlane function uses a single bit plane of the specified source rectan- 
gle combined with the specified GC to modify the specified rectangle of dest. 
The drawables must have the same root but need not have the same depth. If 
the drawables do not have the same root, a BadMatch error results. If plane 
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does not have exactly one bit set to 1 and the values of planes must be less than 
* 2", where n is the depth of src, a BadValue error results. 

Effectively, XCopyPlane forms a pixmap of the same depth as the rectangle of 
dest and with a size specified by the source region. It uses the 
foreground/background pixels in the GC (foreground everywhere the bit plane 
in src contains a bit set to 1, background everywhere the bit plane in src con- 
tains a bit set to 0) and the equivalent of a CopyArea potocol request is per- 
formed with all the same exposure seniantics. This can also be tiiought of as 
using the specified region of the source bit plane as a stipple with a fill-style of 
Fillppac[ueStippled for filling a rectangular area of the destination. 

This function uses these GC components: function, plane-mask, foreground, 
background, subwindow-mode, graphics-exposures, clip-x-origin, clip-y-origin 
and clip-mask. 

XCopyPlane can generate BadDrawable, BadGC, BadMatch, and BadValue 
errors. 
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Xlib provides functions that you can use to draw: 

■ A single point or multiple points 

■ A single line or multiple lines 

■ A single rectangle or multiple rectangles 

■ A single arc or multiple arcs 

Some of the functions described in the following sections use these structures: 

typ&dBf struct { 

short xl, yl, x2, y2; 

> XSeguKit; 

typedet struct { 

short X, y; 

> XPoint; 

typed^t struct { 

short X, y; 

unsignad short width, height; 
} XRectangle; 

typedef struct { 

short X, y; 

unsignsd short width, height ; 

short anglel, angle2; /* Degrees * 64 */ 

> XArc; 

All X and y members are 16-bit signed integers. The width and height members 
are 16-bit unsigned integers. You should be careful not to generate coordinates 
and sizes out of the 16-bit ranges, because the protocol only has 16-bit fields for 
these values. 
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Drawing Single and Multiple Points 

To draw a single point in a given drawable, use XDrawPoint. 

XDrauPoint (display, d, gc, x, y) 
Display ^display; 
Drawable d; 
CCgc; 
int X, y; 



display Spedfies the connection to the XwiN server. 

d Specifies the drawable. 

gc Specifies the GC. 

X 

y Specify the x and y coordinates where you want the point 

drawn. 



To draw multiple points in a given drawable, use XDrawPoint s. 

XDraiiPoints {display, d, gc, points, npoints, mode) 
EHsplay ^display; 
Ehrawable d; 
GC gc ; 

XPoint *points; 
int npoints; 
int mode; 



display Spedfies the connection to the XwiN server. 

d Spedfies the drawable. 

gc Spedfies the GC. 

points Spedfies a pointer to an array of points. 

npoints Specifies the number of points in the array. 

mode Spedfies the coordinate mode. You can pass CoordMcxieOrigin 
or CoordModePrevious. 

6-8 Xwin GWS: Xlib - C Language Interface 



Drawing Points, Lines, Rectangles, and Arcs 



The XDrawPoint function uses the foreground pixel and function components of 
the GC to draw a single point into the specified drawable; XDrawPoints draws 
multiple points this way. 

CoordMcxieOrigin treats all coordinates as relative to the origin, and CoordMo- 
dePrevious treats all coordinates after the first as relative to the previous point. 
XDrawPoints draws the points in the order listed in the array. 

Both functions use these GC components: function, plane-mask, foreground, 
subwindow-mode, clip-x-origin, clip-y-origin, and clip-mask. 

XDrawPoint can generate BadDrawable, BadGC, and BadMatch errors. 
XDrawPoints can generate BadDrawable, BadGC, BadMatch, and BadValue 
errors. 



Drawing Single and Multiple Lines 

To draw a single line between two points in a given drawable, use XDrawLine. 

XDrawLine {display, d, gc, xl,yl, x2, yl) 
Display * display; 
Ehrawable d; 
GCgc; 

int xl, yl, x2, y2; 

display Specifies the connection to the XwiN server. 

d Specifies the drawable. 

gc Specifies the GC. 

xl 

x2 

y2 Specify the points (xl, yl) and (x2, y2) to be connected. 

To draw multiple lines in a given drawable, use XDrawLines. 
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XDraWLlnM {displaif, d, gc, points, npoints, mode) 
Display ^display; 
Drawable d; 
CCgc; 

XPoint ^points; 
int npoints; 
int mode; 



display Specifies the connection to the XwiN server. 

d Specifies the drawable. 

gc Specifies the GC. 

points Specifies a pointer to an array of points. 

npoints Specifies the number of points in the array. 

mode Specifies the coordinate mode. You can pass CoordModeOrigin 
or CoordModePrevlous. 



To draw multiple, unconnected lines in a given drawable, use XDrawSegments. 

XDrawSegnents (display, d, gc, segments, nsegments) 
Display *disp1ay; 
Drawable d; 
CCgc; 

XSegment * segments; 
int nsegments; 



display Specifies the connection to the XwiN server. 

d Specifies the drawable. 

gc Specifies the GC. 

segments Specifies a pointer to an array of segments. 

nsegments Specifies the number of segments in the array. 



The XDrawLine function uses the components of the specified GC to draw a line 
between the specified set of points (xl, yl) and (x2, y2). It does not perform 
joining at coincident endpoints. For any given line, XDrawLine does not draw a 
pixel more than once. If lines intersect, the intersecting pixels are drawn multi- 
ple times. 
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The XDrawLines function uses the components of the specified GC to draw 
npoints-1 lines between each pair of points (point[i], point[i+l]) in the array of 
XPoint structures. It draws the lines in the order listed in the array. The lines 
join correctly at all intermediate points, and if the first and last points coincide, 
the first and last lines also join correctly. For any given line, XDrawLines does 
not draw a pixel more than once. If thin (zero line-width) lines intersect, the 
intersecting pixels are drawn multiple times. If wide lines intersect, the inter- 
secting pixels are drawn only once, as though the entire PolyLine protocol 
request were a single, filled shape. CoordModeOrigin treats all coordinates as 
relative to the origin, and CoordModePrevious treats all coordinates after the 
first as relative to the previous point. 

The XDrawSegments function draws multiple, unconnected lines. For each seg- 
ment, XDrawSegments draws a line between (xl, yl) and (x2, y2). It draws the 
lines in the order listed in the array of XSeginent structures and does not per- 
form joining at coincident endpoints. For any given line, XDrawSeginents does 
not draw a pixel more than once. If lines intersect, the intersecting pixels are 
drawn multiple times. 

All three functions use these GC components: function, plane-mask, line-width, 
line-style, cap-style, fill-style, subwindow-mode, clip-x-origin, clip-y-origin, and 
clip-mask. The XDrawLines function also uses the join-style GC component. 
All three functions also use these GC mode-dependent components: foreground, 
background, tile, stipple, tile-stipple-x-origin, tile-stipple-y-origin, dash-offset, 
and dash-list. 

XDrawLine, XDrawLines, and XDrawSeginents can generate BadDrawable, 
BadGC, and BadMatch errors. XDrawLines also can generate BadValue errors. 

Drawing Single and Multiple Rectangles 

To draw the outline of a single rectangle in a given drawable, use 
XDrawRect angle. 
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XDrauBeotangle (dispUn^, d, gc, x, y, width, height) 
EMsplay ^display; 
Drawable d; 
OZgc; 
int X, y; 

unsigned int width, height; 



display 


Specifies the connection to the XWIN server. 


d 


Specifies the drawable. 




Specifies the GC. 


X 

y 


Specify the x and y coordinates, which specify the upper-left 




comer of the rectangle. 


xmdth 




height 


Specify the width and height, which specify the dimensions of 




the rectangle. 



To draw the outline of multiple rectangles in a given drawable, use XDrawRec- 
tangles. 

XDraitflectangles {display, d, gc, rectangles, nrectangJes) 
Display ^display; 
Drawable d; 
CCgc; 

XRectangle rectanglesl]; 
int nrectangles; 



display Specifies the connection to the XwiN server. 

d Specifies the drawable. 

gc Specifies the GC. 

rectangles Specifies a pointer to an array of rectangles. 

nrectangles Specifies the number of rectangles in the array. 
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The XDrawRectangle and XDrawRectangles functions draw the outlines of the 
specified rectangle or rectangles as if a five-point PolyLdLne protocol request 
were specified for each rectangle: 

[x,y] [x-fwidth,y] [x+width,y+height] [x,y-i-height] [x,y] 

For the specified rectangle or rectangles, these functions do not draw a pixel 
more than once. XDrawRectangles draws the rectangles in the order listed in 
the array. If rectangles intersect, the intersecting pixels are drawn multiple 
times. 

Both functions use these GC components: function, plane-mask, line-width, 
line-style, join-style, fill-style, subwindow-mode, clip-x-origin, clip-y-origin, and 
clip-mask. They also use these GC mode-dependent components: foreground, 
background, tile, stipple, tile-stipple-x-origin, tile-stipple-y-origin, dash-offset, 
and dash-list. 

XDrawRectangle and XDrawRectangles can generate BadDrawable, BadGC, 
and BadMatch errors. 



Drawing Single and Multiple Arcs 

To draw a single arc in a given drawable, use XDrawArc. 

XDrawAro {display, d, gc, x, y, width, height, anglel, angle!) 
Display ^display; 
Drawable d; 
GC gc; 
int X, y; 

imsigned int width, height; 
int anglel, anglel; 

display Specifies the connection to the XwiN server. 

d Specifies the drawable. 

gc Specifies the GC. 

X 

y Specify the x and y coordinates, which are relative to the origin 

of the drawable and specify the upper-left comer of the bound- 
ing rectangle. 
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xmdth 
height 



Specify the width and height, which are the major and minor 
axes of the arc. 



anglel 



Specifies the start of the arc relative to the three-o'clock position 
from the center, in units of degrees 64. 



angle! 



Specifies the path and extent of the arc relative to the start of 
the arc, in units of degrees * 64. 



To draw multiple arcs in a given drawable, use XDrawArcs. 

XDrawAros (display, d, gc, arcs, narcs) 
Display ^display; 
Drawable d; 
CCgc; 
XArc *flrcs; 
int narcs; 

display Specifies the connection to the XwiN server. 

d Specifies the drawable. 

gc Specifies the GC. 

arcs Specifies a pointer to an array of arcs. 

narcs Specifies the number of arcs in the array. 

XDrawArc draws a single circular or elliptical arc, and XDrawArcs draws multi- 
ple circular or elliptical arcs. Each arc is specified by a rectangle and two 
angles. The center of the circle or ellipse is the center of the rectangle, and the 
major and minor axes are specified by the width and height. Positive angles 
indicate counterclockwise motion, and negative angles indicate clockwise 
motion. If the magnitude of angle2 is greater than 360 degrees, XDrawArc or 
XDrawArcs truncates it to 360 degrees. 

For an arc specified as [ x, y, mdth,^eight,^ anglel, anglel], the origin of the 
major and minor axes is at [x+ , y+ -^^-^l, and the infinitely thin path 
describmg the entire circle or elli^se^intersects the horizontal axis at 
[x, y+ ^^^^ ] and [x+mdth, y+ -^^1 and intersects the vertical axis at 

lx+ , y] and y-^height]. These coordinates can be fractional and 
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so are not truncated to discrete coordinates. The path should be defined by the 
ideal mathematical path. For a wide line with line-width Iw, the bounding out- 
lines for filling are given by the two infinitely thin paths consisting of all points 
whose perpendicular distance from the path of the drcle/ellipse is equal to 
lw/2 (which may be a fractional value). The cap-style and join-style are applied 
the same as for a line corresponding to the tangent of the circle/ellipse at the 
endpoint. 

For an arc specified as [ x, y, width, height, angle 1, angle!], the angles must be 
specified in the effectively skewed coordinate system of the ellipse (for a circle, 
the angles and coordinate systems are identical). The relationship between these 
angles and angles expressed in the nomnal coordinate system of the screen (as 
measured with a protractor) is as follows: 



skewed-angle = atan 



tan(normal'-angle)'^ -r-^~- 
°^ height 



+ ad just 



The skewed-angle and normal-angle are expressed in radians (rather than in 
degrees scaled by 64) in the range [0, 2k] and where atan returns a value in the 

range [- —] and adjust is: 

0 for nonnal-angle in the range [0, y] 

n for normal -angle in the range [y, ^] 

2n for normal-angle in the range [— , 2n] 



For any given arc, XDrawArc and XDrawArcs do not draw a pixel more than 
once. If two arcs join correctly and if the line-width is greater than zero and the 
arcs intersect, XDrawArc and XDrawArcs do not draw a pixel more than once. 
Otherwise, the intersecting pixels of intersecting arcs are drawn multiple times. 
Specifying an arc with one endpoint and a dodkwise extent draws the same pix- 
els as specifying the other endpoint and an equivalent counterclockwise extent, 
except as it affects joins. 

If the last point in one arc coincides with the first point in the following arc, the 
two arcs will join correctly. If the first point in the first arc coincides with the 
last point in the last arc, the two arcs will join correctly. By specifying one axis 
to be zero, a horizontal or vertical line can be drawn. Angles are computed 
based solely on the coordinate system and ignore the aspect ratio. 
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Both functions use these GC components: function, plane-mask, line-width, 
line-style, cap-style, join-style, fill-style, subwindow-mode, clip-x-origin, clip-y- 
origin, and dip-mask. They also use these GC mode-dependent components: 
foreground, background, tile, stipple, tile-stipple-x-origin, tile-stipple-y-origin, 
dash-offset, and dash-list. 

XDrawArc and XDrawArcs can generate BadDrawable, BadGC, and Bad^4atch 
errors. 
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Xlib provides functions that you can use to fill: 

■ A single rectangle or multiple rectangles 

■ A single polygon 

■ A single arc or multiple arcs 



Filling Single and Multiple Rectangles 

To fill a single rectangular area in a given drawable, use XFillRectangle. 

XFillBectangle {display, d, gc, x, y, width, height) 
Display ^display; 
Drawable d; 
GC gc; 
int X, y; 

unsigned int width, height; 

display Specifies the connection to the XwiN server. 

d Specifies the drawable. 

gc Specifies the GC. 

X 

y Specify the x and y coordinates, which are relative to the origin 

of the drawable and specify the upper-left comer of the rectan- 
gle. 

mdth 

height Specify the width and height, which are the dimensions of the 

rectangle to be filled. 

To fill multiple rectangular areas in a given drawable, use XFillRectangles. 
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XFillBiectangles {display, d, gc, rectangles, nrectangles) 
Display *display; 
Drawable d; 
GCgc; 

XRectangle ^rectangles; 
int nrectangles; 

display Specifies the connection to the XwiN server. 

d Specifies the drawable. 

gc Specifies the GC. 

rectangles Specifies a pointer to an array of rectangles. 
nrectangles Specifies the number of rectangles in the array. 

The XFillRectangle and XFlllRectangles functions fill the specified rectan- 
gle or rectangles as if a four-point FillPolygon protocol request were specified 
for each rectangle: 

[x,y] [x4width,y] [x+width, y4hei^t] [x,y4height] 

Each function uses the x and y coordinates, width and height dimensions, and 
GC you specify. 

XFlllRectangles fills the rectangles in the order listed in the array. For any 
given rectangle, XFillRectangle and XFlllRectangles do not draw a pixel 
more than once. If rectangles intersect, the intersecting pixels are drawn multi- 
ple times. 

Both functions use these GC components: function, plane-mask, fill-style, 
subwindow-mode, clip-x-origin, clip-y-origin, and clip-mask. They also use 
these GC mode-dependent components: foreground, background, tile, stipple, 
tile-stipple-x-origin, and tile-stipple-y-origin. 

XFillRectangle and XFlllRectangles can generate BadDrawable, BadGC, 
and BadMatch errors. 
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Filling a Single Polygon 

To fill a polygon area in a given drawable, use XFillPolygon. 

XFillPolygon (<iisp2ay, d, gc, points, npoints, shape, mode) 
Display ^displaif; 
Drawable d; 
GC gc; 

XPdnt ^points; 
int npoints; 
int shape; 
int mode; 



display 


Specifies the connection to the XWIN server. 


d 


Specifies the drawable. 




Specifies the GC 


points 


Specifies a pointer to an array of points. 


npoints 


Specifies the number of points in the array. 


shape 


Specifies a shape that helps the server to improve performance. 
You can pass Ccxiplex, Convex, or Nonconvex. 


mode 


Specifies the coordinate mode. You can pass CoordModeOrigin 



or CoordModePrevious. 

XFillPolygon fills the region closed by the specified path. The path is closed 
automatically if the last point in the list does not coincide with the first point. 
XFillPolygon does not draw a pixel of the region more than once. 
CoordModeOrigin treats all coordinates as relative to the origin, and CoordMo- 
dePrevious treats all coordinates after the first as relative to the previous point, 

Depending on the specified shape, the following occurs: 

■ If shape is Coinplex, the path may self-intersect. 

■ If shape is Convex, the path is wholly convex. If known by the client, 
specifying Convex can improve performance. If you specify Convex for a 
path that is not convex, the graphics results are undefined. 
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■ If shape is Nonconvex, the path does not self-intersect, but the shape is 
not wholly convex. If known by the client, specifying Nonconvex instead 
of Ccmqplex may improve performance. If you specify Nonconvex for a 
self-intersecting path, the graphics results are undefined. 

The fill-rule of the GC controls the filling behavior of self-intersecting polygons. 

This function uses these GC components: function, plane-mask, fill-style, fill- 
rule, subwindow-mode, clip-x-origin, clip-y-origin, and clip-mask. It also uses 
these GC mode-dependent components: foreground, background, tile, stipple, 
tile-stipple-x-origin, and tile-stipple-y-origin. 

XFillPolygon can generate BadDrawable, BadGC, BadMatch, and BadValue 
errors. 



Filling Single and Multiple Arcs 

To fill a single arc in a given drawable, use XFillArc. 

XFillArc {display, d, gc, x, y, width, height, mglel, angle!) 
Display ^display; 
Drawable d; 
GCgc; 
int X, y; 

unsigned int width, height; 
int anglel, angle!) 

Specifies the connection to the XwiN server. 
Specifies the drawable. 
Specifies the GC. 

Specify the x and y coordinates, which are relative to the origin 
of the drawable and specify the upper-left comer of the bound- 
ing rectangle. 

Specify the width and height, which are the major and minor 
axes of the arc. 



display 
d 

X 

y 

xvidth 
height 
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anglel Specifies the start of the arc relative to the three-o'clock position 

from the center, in units of degrees * 64. 

anglel Specifies the path and extent of the arc relative to the start of 

the arc, in units of degrees * 64. 

To fill multiple arcs in a given drawable, use XFillArcs. 

XFillArcss {display, d, gjc, arcs, narcs) 
Display *display; 
Ehrawable d; 
GCgc; 
XArc *arcs; 
int narcs; 



display 


Specifies 


the connection to the XwiN server. 


d 


Specifies 


the drawable. 




Specifies 


the GC. 


arcs 


Specifies 


a pointer to an array of arcs. 


narcs 


Specifies 


the number of arcs in the array. 



For each arc, XFillArc or XFillArcs fills the region closed by the infinitely 
thin path described by the specified arc and, depending on the arc-mode 
specified in the GC, one or two line segments. For ArcChord, the single line seg- 
ment joining the endpoints of the arc is used. For ArcPieSlice, the two line 
segments joining the endpoints of the arc with the center point are used. 
XFillArcs fills the arcs in the order listed in the array. For any given arc, 
XFillArc and XFillArcs do not draw a pixel more than once. If regions inter- 
sect, the intersecting pixels are drawn multiple times. 

Both functions use these GC components: function, plane-mask, fill-style, arc- 
mode, subwindow-mode, clip-x-origin, clip-y-origin, and clip-mask. They also 
use these GC mode-dependent components: foreground, background, tile, stip- 
ple, tile-stipple-x-origin, and tile-stipple-y-origin. 

XFillArc and XFillArcs can generate BadDrawable, BadGC, and BadMatch 
errors. 
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A font is a graphical description of a set of characters that are used to increase 
efficiency whenever a set of small, similar sized patterns are repeatedly used. 

This section discusses how to: 

■ Load and free fonts 

■ Obtain and free font names 

■ Set and retrieve the font search path 

■ Compute character string sizes 

■ Return logical extents 

■ Query character string sizes 



The XwiN server loads fonts whenever a program requests a new font. The 
server can cache fonts for quick lookup. Fonts are global across all screens in a 
server. Several levels are possible when dealing with fonts. Most applications 
simply use XLoadQueryFont to load a font and query the font metrics. 

Characters in fonts are regarded as masks. Except for image text requests, the 
only pixels modified are those in which bits are set to 1 in the character. This 
means that it makes sense to draw text using stipples or tiles (for example, 
many menus gray-out unusable entries). 

The XFontStruct structure contains all of the information for the font and con- 
sists of the font-specific information as well as a pointer to an array of XChar- 
Struct structures for the characters contained in the font. The XFontStruct, 
XFontProp, and XCharStruct structures contain: 

t^pedef struct { 

short Ibearing; /* origin to le£t edge of raster */ 

short rbearing; /* origin to right edge of raster */ 

short width; /* advanoe to next cSiar' s origin */ 

short asoent; /* baseline to top edge of raster */ 

short desoent; /* baseline to bottom edge of raster */ 

unsigned short attributes; /* per daar flags (not predefined) */ 
> XCharStruct; 
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typadsf struct { 

Atom name; 

unsigned long cazd32; 
> XPontProp; 



typedef struct { /* normal 16 bit characters are two bytes */ 

unsigned obar bytel; 

unsigned char byte2; 
> XChar2b; 



typedef struct { 

XBxtData *extjdata; /* 

Pont fid; /* 

unsigned direction; /* 

unsigned minjcharjorJ»yte2; /* 

unsigned maxjciiarjorJ;>yte2; /* 

unsigned min^bytel; /* 

unsigned maxjbytel; /* 

Bool alljcfaarsjudst; /* 

unsigned defaultjchar; /* 

int njproperties; /* 

XFontProp properties; /* 

XCbarStruct minjaounds; /* 

XCharStruct maxjxxinds; /* 

XCharStruct *perjdiar; /* 

int ascent; /* 

int descent; /* 

} XFontStruct; 



hook for extension to hang data */ 

Font id for this font */ 

hint about the direction font is painted */ 

first character */ 

last ciiaracter */ 

first row that exists */ 

last row that exists */ 

flag if all characters have nonzero size */ 

char to print for undefined cdaaracter */ 

how many properties there are */ 

pointer to array of additional properties */ 

minimim bounds over all existing char */ 

maxiimmi bounds over all existing char V 

first jchar to last^diar information */ 

logical extent above baseline for ^(pacing */ 

logical decent below baseline for upacing */ 



X supports single b5^e/character, two bytes/character matrix, and 16-bit charac- 
ter text operations. Note that any of these forms can be used with a font, but a 
single byte/character text request can only specify a single byte (that is, the first 
row of a 2-byte font). You should view 2-byte fonts as a two-dimensional 
matrix of defined characters: bytel specifies the range of defined rows and byte2 
defines the range of defined colunms of the font. Single byte/character fonts 
have one row defined, and the byte2 range specified in the structure defines a 
range of characters. 
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The bounding box of a character is defined by the XCharStruct of that charac- 
ter. When characters are absent from a font, the default^char is used. When 
fonts have all characters of the same size, only the information in the 
XFontStruct min and max bounds are used. 

The members of the XFontStruct have the following semantics: 

■ The direction member can be either FontLef tToRight or FontRight- 
ToLeft. It is just a hint as to whether most XCharStruct elements have 
a positive ( FontLeftToRight ) or a negative { FontRightToLef t ) char- 
acter width metric. The core protocol defines no support for vertical text 

■ If the minjjytel and max^bytel members are both zero, 
min_char_or_byte2 specifies the linear character index corresponding to 
the first element of the per_char array, and maxjchar_or Jbyte2 specifies 
the linear character index of the last element 

If either minj>3rtel or max^bytel are nonzero, both min_char_or_byte2 
and max_char_or_byte2 are less than 256, and the 2-byte character index 
values corresponding to the per char array element N (counting from 0) 
are: 

bytel = N/D + minbytel 

byte2 = N\D + nun_char_or J>yte2 

where: 

D = max_char_or Jbyte2 - min_char_pr_byte2 + 1 
/ = integer division 
\ = integer modulus 

■ If the per_char pointer is NULL, all glyphs between the first and last char- 
acter indexes inclusive have the same information, as given by both 
min_bounds and maxjbounds. 

■ If all_chars_exist is True, all characters in the per_char array have 
nonzero bounding boxes. 

■ The default_char member specifies the character that will be used when 
an undefined or nonexistent character is printed. The default_char is a 16- 
bit character (not a 2-b)rte character). For a font using 2-byte matrix for- 
mat, the default_char has bytel in the most-significant byte and byte2 in 
the least-significant byte. If the default_char itself specifies an undefined 
or nonexistent character, no printing is performed for an undefined or 
nonexistent character. 
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■ The minjx)unds and inax__bounds members contain the most extreme 
values of each individual XCharStruct component over all elements of 
this array (and ignore nonexistent characters). The bounding box of the 
font (the smallest rectangle enclosing the shape obtained by superimpos- 
ing all of the characters at the same origin [x,y]) has its upper-left coordi- 
nate at: 

[x -¥ minjMunds.lbearing, y - maxjdounds.aaoent] 

Its width is: 

inax^boundB.xbaariiig - min^bounds.Ibearing 

Its height is: 

maxj>ound8.aaoent + iiiaxjx>und8. descent 

■ The ascent member is the logical extent of the font above the baseline that 
is used for determining line spacing. Specific characters may extend 
beyond this. 

■ The descent member is the logical extent of the font at or below the base- 
line that is used for determining line spacing. Specific characters may 
extend beyond this. 

■ If the baseline is at Y-coordinate y, the logical extent of the font is 
inclusive between the Y-coordinate values (y ~ font.ascent) and (y + 
font.descent - 1). Typically, the minimum interline spacing between rows 
of text is given by ascent + descent. 

For a character origin at [x,y], the bounding box of a character (that is, the smal- 
lest rectangle that encloses the character's shape) described in terms of XChar- 
Struct components is a rectangle with its upper-left comer at: 

[X -¥ Ibearing, y - ascent] 

Its width is: 

rbearing - Ibearing 
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Its height is: 

asoent dMoent 

The origin for the next character is defined to be: 

[X -I- width, y] 

The Ibearing member defines the extent of the left edge of the character ink 
from the origin. The rbearing member defines the extent of the right edge of 
the character ink from the origin. The ascent member defines the extent of the 
top edge of the character ink from the origin. The descent member defines the 
extent of the bottom edge of the character ink from the origin. The width 
member defines the logical width of the character. 

Note that the baseline (the y position of the character origin) is logically viewed 
as being the scanline just below nondescending characters. When descent is 
zero, only pixels with Y-coordinates less than y are drawn, and the origin is log- 
ically viewed as being coincident with the left edge of a nonkemed character. 
When Ibearing is zero, no pixels with X-coordinate less than x are drawn. Any 
of the XCharStruct metric members cotild be negative. If the width is nega- 
tive, the next character will be placed to the left of the current origin. 

The X protocol does not define the interpretation of the attributes member in 
the XCharStruct structure. A nonexistent character is represented with all 
members of its XCharStruct set to zero. 

A font is not guaranteed to have any properties. The interpretation of the pro- 
perty value (for example, long or unsigned long) must be derived from a priori 
knowledge of the property. When possible, fonts should have at least the pro- 
perties listed in the table. With atom names, uppercase and lowercase matter. 
The following built-in property aton\s can be found in < Xll/Xatcm.h >: 
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Property Name 



Type 



Description 



MIN_SPACE 
NORM_SPACE 
MAX_SPACE 
END_SPACE 

SUPERSCRIPT_X 
SUPERSCWr Y 



SUBSCRIPT_X 
SUBSCRIPT Y 



UNDERLINE POSmON 



UNDERUNE.THICKNESS 

STRIKEOUT_ASCENT 
STRIKEOUT DESCENT 



ITALIC ANGLE 



X HEIGHr 



QUAD_WIDTH 



unsigned 
unsigned 
unsigned 
unsigned 

int 



int 



int 



unsigned 
int 



int 



int 
int 



The minimum interword spacing, in pixels. 

The normal interword spacing, in pixels. 

The maximum interword spacing, in pixels. 

The additional spacing at the end of sentences, in 
pixels. 

Offset from the character origin where super- 
scripts should begin, in pixels. If the origin is at 
[x,y], then supersaipts should begin at 
[x + SUPERSCRIPT_X, y - SUPERSCRIPT_Y]. 

Offset from the character origin where subscripts 
should begin, in pixels. If the origin is at [x,yl, 
then subscripts should begin at 
(x -f SUPERSCRIPT^^ y + SUPERSCRIPT_Y]. 

Y offset from the baseline to the top of an tmder- 
line, in pixels. If the baseline is Y-coordinate y, 
then the top of the imderline is at 
(y + UNDERLINE_POSrnON). 

Thickness of die underline, in pixels. 

Vertical extents for boxing or voiding characters, 
in pixels. If the baseline is at Y-coordinate y, 
then the top of the strikeout box is at 
(y - STRIKEOUT_ASCENT), 
and the height of the box is 
(STRIKEOUT_ASCENT + STRIKEOUT_DESCENT). 

The angle of the dominant staffs of characters in 
the font, in degrees scaled by 64, relative to the 
three-o'clock position from ttie character origin, 
with positive indicating counterclockwise motion 
(as in XDrawArc). 

1 ex as in TeX, but expressed in units of pixels. 
Often the height of lowercase x. 

1 em as in TeX, but expressed in units of pixels. 
Often the width of the digits 0-9. 
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Property Name 



Type 



Description 



CAP HEIGHT 



int 



Y offset from the baseline to the top of the capital 
letters, ignoring accents, in pixels. If the basdine 
is at Y-coordinate y, then the top of the capitals is 
at(jr- CAP_HEIGHD. 



WEIGHT 



unsigned 



The weight or boldness of the font, expressed as 
a value between 0 and 1000. 



POINT SIZE 



unsigned 



The point size of this font at the ideal resolution, 
expressed in 1/10 points. 



RESOLUTION 



unsigned 



The number of pixels per point, expressed in 
1/100, at which this font was created. 



Loading and Freeing Fonts 



Xlib provides functions that you can use to load fonts, get font information, 
unload fonts, and free font information. A few font functions use a GContext 
resource ID or a font ID interchangeably. 

To load a given font, use XLoadFont. 

Font XLoadFont {display, name) 
Display * display; 
char *mme; 

display Specifies the connection to the XwiN server. 

name Specifies the name of the font, which is a null-terminated string. 

The XLoadFont function loads the specified font and returns its associated font 
ID. The name should be ISO Latin-1 encoding; uppercase and lowercase do not 
matter. If XLoadFont was unsuccessful at loading the specified font, a BadName 
error results. Fonts are not associated with a particular screen and can be stored 
as a component of any GC. When the font is no longer needed, call XUnload- 
Font. 

XLoadFont can generate BadAlloc and BadNaxne errors. 
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To return information about an available font, use XQuezyFont. 



XFontStmct *yQai&r^oat {display, font JD) 
Display *display; 
XID fbntJD; 



display 
fontJD 



Specifies the connection to the XwiN server. 
Specifies the font ID or the GContext ID. 



The XQueryFont function returns a pointer to the XFontStruct structure, which 
contains information associated with the font. You can query a font or the font 
stored in a GC The font ID stored in the XFontStruct structure will be the 
GContext ID, and you need to be careful when using this ID in other functions 
(see XGContextFroniGC). To free this data, use XFreeFontlnfo. 

To perform a XLoadFont and XQueiyFont in a single operation, use XLoad- 
QueryFont. 

XFontStruct *XU>adQmr^ont (display, name) 
EHsplay ^display; 
char *nanie; 

display Specifies the connection to the XwiN server. 

name Specifies the name of the font, which is a null-terminated string. 

The XLoadQueryFont function provides the most common way for accessing a 
font. XLoadQueryFont both opens (loads) the specified font and returns a 
pointer to the appropriate XFontStruct structure. If the font does not exist, 
XLoadQueryFont returns NULL. 

XLoadQueryFont can generate a BadMloc error. 

To unload the font and free the storage used by the font structure that was allo- 
cated by XQueryFont or XLoadQueryFont, use XFreeFont. 

XFzeeFont (display, fontjtruci) 
Display * display] 
XFontStmct *fontjtTuct; 

display Specifies the connection to the XwiN server. 
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font^stmct Specifies the storage associated with the font. 

The XFreeFont function deletes the association between the font resource ID 
and the specified font and frees the XFontStruct structure. The font itself will 
be freed when no other resource references it. The data and the font should not 
be referenced again. 

XFreeFont can generate a BadFont error. 

To return a given font property, use XGetFontProperty. 

Bool XSetFontPxoperty (/bn{_s^ct, atom, value jetum) 
XFontStruct *fontjtruct; 
Atom atom; 

iinsigned long *value_retum; 

font__struct Specifies the storage associated with the font. 

atom Specifies the atom for the property name you want returned. 

value jeturn Returns the value of the font property. 

Given the atom for that property, the XGetFontProperty function returns the 
value of the specified font property. XGetFontProperty also returns False if 
the property was not defined or True if it was defined. A set of predefined 
atoms exists for font properties, which can be found in < Xll/Xatora.h >. This 
set contains the standard properties associated with a font Although it is not 
guaranteed, it is likely that the predefined font properties will be present 

To unload a font that was loaded by XLoadFont, use XCJnloadFont. 

XUhloadFont {display, font) 
Display ^display; 
Font font; 

display Specifies the connection to the XWIN server. 

font Specifies the font 

The XUnloadFont function deletes the association between the font resource ID 
and the specified font. The font itself will be freed when no other resource 
references it. The font should not be referenced again. 



6-30 



Xwin QWS: Xlib - C Language Interface 



Font Metrics 



XUnloadFont can generate a BadFont error. 

Obtaining and Freeing Font Names and Information 

You obtain font names and information by matching a wildcard specification 
when querying a font type for a list of available sizes and so on. 

To return a list of the available font names, use XLlstFonts. 

dhar **XLi8tFonts {display, pattern, maxnames, actual jxmntjretum) 
Display ^display; 
char ^pattern; 
int tnaxnamtsi 
int *actualjxnmtjetum; 

display Specifies the connection to the XwiN server. 

pattern Specifies the null-terminated pattern string that can contain 

wildcard characters. 

maxnames Specifies the maximum number of names to be returned. 

actualjx)unt_retum 

Returns the actual number of font names. 

The XListFonts function returns an array of available font names (as controlled 
by the font search path; see XSetFontPath) that match the string you passed to 
the pattern argument. The string should be ISO Latin-1; uppercase and lower- 
case do not matter. Each string is terminated by an ASCII null. The pattern 
string can contain any characters, but each asterisk C^) is a wildcard for any 
nun^r of characters, and each question mark (?) is a wildcard for a single char- 
acter. The client should call XFreeFontKfames when finished with the result to 
free the memory. 

To free a font name array, use XFreeFontNames. 

XFreeFontNanes (list) 
char *listl]; 
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list Specifies the array of strings you want to free. 

The XFreeFontNames function frees the array and strings returned by XLlst- 
Fonts or XListFontsWithlnfo. 

To obtain the names and information about available fonts, use XList- 
FontsWithlnfo. 

char **XLi8tFont8WithIn£o (ilis^xlay, pattern, maxnames, count jetum, infojetum) 
Display ^display; 
char ^pattern; 
int maxnames; 
int *countjretum; 
XFontStnict **infojetum; 

display Specifies the connection to the XwiN server. 

pattern Specifies the null-terminated pattern string that can contain 

wildcard characters. 

maxnames Specifies the maximum number of names to be returned. 

count jetum Returns the actual number of matched font names. 

info jetum Returns a pointer to the font information. 

The XListFontsWithlnfo function returns a list of font names that match the 
specified pattern and their associated font information. The list of names is lim- 
ited to size specified by maxnames. The information returned for each font is 
identical to what XLoadQueryFont would return except that the per-character 
metrics are not returned. The pattern string can contain any characters, but 
each asterisk (*) is a wildcard for any number of characters, and each question 
mark (?) is a wildcard for a single character. To free the allocated name array, 
the client should call XFreeFontNames. To free the the font information array, 
the client should call XFreeFontlnfo. 

To free the the font information array, use XFreeFontlnfo. 

XFreeFontlnfo {names, freejnjb, actual jxmnt) 
char **names; 
XFontStruct *freejnfd; 
int actual count; 
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names Specifies the list of font names returned by XList- 

FontsWithlnfo. 

freejnfo Specifies the pointer to the font infonnation returned by XList- 

FontsWithlnfo. 

actualj:ount Specifies the actual number of matched font names returned by 
XListFontsWithlnfo. 



Setting and Retrieving the Font Search Path 

To set the font search path, use XSetFontPath. 

XSetFontPath (display, directories, ndirs) 
Display ^display; 
char **directories; 
int ndirs; 

display Specifies the connection to the XwiN server. 

directories Specifies the directory path used to look for a font. Setting the 
path to the empty list restores the default path defined for the 
XwiN server. 

ndirs Specifies the number of directories in the path. 

The XSetFontPath function defines the directory search path for font lookup. 
There is only one search path per XwiN server, not one per client The interpre- 
tation of the strings is operating system dependent, but they are intended to 
specify directories to be searched in the order listed. Also, the contents of these 
strings are operating system dependent and are not intended to be used by 
client applications. Usually, the XwiN server is free to cache font information 
intemaUy rather than having to read fdnts from files. In addition, the XwiN 
server is guaranteed to flush all cached information about fonts for which there 
currently are no explicit resource IDs allocated. The meaning of an error from 
this request is operating system dependent. 

XSetFontPath can generate a BadValue error. 
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To get the current font search path, use XGetFontPath. 

char **XSetFontPath(<fisp2^y, npa^^nefMiTi) 
Display * display; 
int *npaihsjretum; 

display Specifies the connection to the XWIN server. 

npathsjetum Returns the number of strings in the font path array. 

The XGetFontPath function allocates and returns an array of strings containing 
the search path. When it is no longer needed, the data in the font path should 
be freed by using XFreeFontPath. 

To free data returned by XGetFontPath, use XFreeFontPath. 

XFietfontPath (lisO 
char 

list Specifies the array of strings you want to free. 

The XFreeFontPath function frees the data allocated by XGetFontPath. 



Computing Character String Sizes 

Xlib provides functions that you can use to compute the width, the logical 
extents, and the server information about 8-bit and 2-byte text strings. The 
width is computed by adding the character widths of all the characters. It does 
not matter if the font is an 8-bit or 2-byte font. These functions return the sum 
of the character metrics, in pixels. 

To detennine the width of an 8-bit character string, use XTextWidth. 

int XTextWidth {pmtjtruct, string, count) 
XFontStruct *fdntjtruct; 
char *string; 
int count; 

font_struct Specifies the font used for the width computation. 



6-34 



Xwin GWS: Xiib - C Unguage Interface 



Font Metrics 

string Specifies the character string. 

count Specifies the character count in the specified string. 

To determine the width of a 2-byte character string, use XTextWidthl6. 

int XIextWidthl6 (/bnt^smtt:^ string, count) 
XFontStnict *pntjtruct; 
XChar2b ^string; 
int count; 

fontjtruct Specifies the font used for the width computation. 

string Specifies the character string. 

count Specifies the character count in the specified string. 

Computing Logical Extents 

To compute the bounding box of an 8-bit character string in a given font, use 
XText Extents. 

XTaxtExtentB {pmtjtmct, string, nchars, direction jreturn, font jiscentjetum, 
fontjkscentjretum, oomdljetum) 
XFontStnict ^fontjtruct; 
char ^string] 
int nchars; 
int *directvon_retum; 

int *pntjiscentjretnm, *fontJiescentjetum; 
XChaiStruct *overdUjretum; 

fontjtruct Specifies a pointer to the XFontStruct structure. 
string Specifies the character string. 

nchars Specifies the number of characters in the character string. 

iirectionjetum 

Returns the value of the direction hint ( FontLeftToRight or 
FontRightToLeft). 
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fontjiscent_retum 

Returns the font ascent. 

font_descent_retum 

Returns the font descent. 

overalljetum Returns the overall size in the specified XCharStruct structure. 

To compute the bounding box of a 2-byte character string in a given font, use 
XTextExtentsl6. 

XTextBxt6ntsl6 {font^struct, string, nchars, directionjetum, fonijiscenijretum, 
fmtjiescentjetum, overattjretum) 
XFontStruct *f(mtjtruct; 
XChar2b ^string; 
int nchars; 
int *directionj^tum; 

int ^fontjiscentjetum, ^fontJUscentjetum) 
XChaiStnict *overtdlj^tum; 

fontjtruct specifies a pointer to the XFontStruct structure. 
string Specifies the character string. 

nchars Specifies the number of characters in the character string. 

directionjeturn 

Returns the value of the direction hint ( FontLeftToRight or 
FontRightToLeft). 

fontjiscentjetum 

Returns the font ascent. 

fontjiescentjretum 

Returns the font descent 

overalljetum Returns the overall size in the specified XCharStruct structure. 

The XTextExtents and XTextExtentsl6 functions perform the size computa- 
tion locally and, thereby, avoid the round-trip overhead of XQueryTextExtents 
and XQueryTextExtentsl6. Both functions return an XCharStruct structure, 
whose members are set to the values as follows. 
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The ascent member is set to the maximum of the ascent metrics of all characters 
in the string. The descent member is set to the maximum of the descent 
metrics. The width member is set to the sum of the character-width metrics of 
all characters in the string. For each character in the string, let W be the sum of 
the character-width metrics of all characters preceding it in the string. Let L be 
the left-side-bearing metric of the character plus W. Let R be the right-side- 
bearing metric of the character plus W. The Ibearing member is set to the 
minimum L of all characters in the string. The rbearing member is set to the 
maximum R. 

For fonts defined with linear indexing rather than 2-byte matrix indexing, each 
XChar2b structure is interpreted as a 16-bit number with bytel as the most- 
significant byte. If the font has no defined default character, undefined charac- 
ters in the string are taken to have all zero metrics. 

Querying Character String Sizes 

To query the server for the bounding box of an 8-bit character string in a given 
font, use XQueryTextExtents. 

XQuexyTextBxtents {display, fontJD, string, nchars, directUmjretum, pntjiscent_retum, 
pntjkscentjetum, ooendljretum) 
Display *display; 
XID fontJD; 
char *string; 
int nchars; 
int *directicm_retum; 

int *fbntjiscentjretum, *font_descentjetum; 
XChaiStruct *overdllj^tum; 

Specifies the connection to the XwiN server. 

Specifies either the font ID or the GContext ID that contains the 
font. 

Specifies the character string. 

Specifies the number of characters in the character string. 



display 
fontJD 

string 
nchars 
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direction_return 

Returns the value of the direction hint ( FontLef tToRight or 
FontRightToLeft)- 

fontjiscent_retum 

Returns the font ascent. 

font_de$centjretum 

Returns the font descent. 

overalljretum Returns the overall size in the specified XCharStruct structure. 

To query the server for the bounding box of a 2-byte character string in a given 
font, use XCiueryTextExtentslS. 

XQiiezyTextExtent8l6 (<ffsp%, fontJD, string, nchars, directkmjreturn, font jiscentjretum, 
pnt_descentjretum, aoertdljretum) 
Display *display; 
XLDfontJD; 
XChar2b *string; 
int nchars; 
int * direction jretum; 

int *font Jiscentjretum, *fimtjiescentjetum; 
XChaiStruct ^overalljretum; 

display Specifies the connection to the XwiN server. 

fontJD Specifies either the font ID or the GContext ID that contains the 

font. 

string Specifies the character string. 

nchars Specifies the number of characters in the character string. 

directionjreturn 

Returns the value of the direction hint ( FontLeftToRight or 
FontRightToLeft). 

fontjiscent_retum 

Returns the font ascent. 

font_descent_retum 

Returns the font descent 



6-38 



Xwin GWS: Xlib - C Unguage Interface 



Font Metrics 



overall jetum Returns the overall size in the specified XCharStruct structure. 

The XQueryTextExtents and XQueryText£xtentsl6 functions return the 
bounding box of the specified 8-bit and 16-bit character string in the specified 
font or the font contained in the specified GC. These functions query the XwiN 
server and, therefore, suffer the round-trip overhead that is avoided by XTex- 
tExtents and XTextEsctentslS. Both functions return a XCharStruct struc- 
ture, whose members are set to the values as follows. 

The ascent member is set to the maximum of the ascent metrics of all characters 
in the string. The descent member is set to the maximum of the descent 
metrics. The width member is set to the sum of the character-width metrics of 
all characters in the string. For each character in the string, let W be the sum of 
the character-width metrics of all characters preceding it in the string. Let L be 
the left-side-bearing metric of the character plus W. Let R be the right-side- 
bearing metric of the character plus W. The Ibearing member is set to the 
minimum L of all characters in the string. The rbearing member is set to the 
maximum R. 

For fonts defined with linear indexing rather than 2-byte matrix indexing, each 
XChar2b structure is interpreted as a 16-bit number with bytel as the most- 
significant byte. If the font has no defined default character, undefined charac- 
ters in the string are taken to have all zero metrics. 

XQueryTextExtents and XQueryTextExtentsl6 can generate BadFont and 
BadGC errors. 
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This section discusses how to draw: 

■ Complex text 

■ Text characters 

■ Image text characters 

The fundamental text functions XDrawText and XDrawTextl6 use the following 
structures. 

typedef struct { 

char ^chars; 

int ncdiars; 

int delta; 

Font font; 
} XTextltem; 

typedef struct { 

XChar2b *chars; 

int nchars; 

int delta; 

Font font; 
} ^extltemlS; 

If the font member is not None, the font is changed before printing and also is 
stored in the GC. If an error was generated during text drawing, the previous 
items may have been drawn. The baseline of the characters are drawn starting 
at the X and y coordinates that you pass in the text drawing functions. 

For example, consider the background rectangle drawn by XDrawImgeString. 
If you want the upper-left comer of the background rectangle to be at pixel 
coordinate (x,y), pass the (x,y + ascent) as the baseline origin coordinates to the 
text functions. The ascent is the font ascent, as given in the XFontStruct struc- 
ture. If you want the lower-left comer of the background rectangle to be at 
pixel coordinate (x,y), pass the (x,y - descent + 1) as the baseline origin coordi- 
nates to the text functions. The descent is the font descent, as given in the 
XFontStruct structure. 



/* pointer to string */ 

/* nunber of ciuuracters */ 

/* delta between strings */ 

/* Font to print it in. None don't ciiange */ 



/* pointer to two-byte characters */ 

/* nunober of diaracters */ 

/* delta between strings */ 

/* font to print it in. None don't change */ 
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Drawing Complex Text 

To draw 8-bit characters in a given drawable, use XDrawText. 

XDrawToxt {display, d, gc, x, y, items, nitems) 
Display ^display; 
Drawable d; 
GC gc; 
int X, y; 

XTextltem *items; 
int nitems; 



display Specifies the connection to the XwiN server. 

d Specifies the drawable. 

gc Specifies the GC. 

X 

y Specify the x and y coordinates, which are relative to the origin 

of the specified drawable and define the origin of the first char- 
acter. 

items Specifies a pointer to an array of text items. 

nitems Specifies the number of text items in the array. 



To draw 2-byte characters in a given drawable, use XDrawTextl6. 

XDrawTextl6 {display, d, gc, x, y, items, nitems) 
Display * display; 
Drawable d; 
GCgc; 
int X, y; 

XTextIteml6 ♦items; 
int nitems; 

display Specifies the connection to the XwiN server. 

d Specifies the drawable. 

gc Specifies the GC. 
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X 



y 



Specify the x and y coordinates, which are relative to the origin 
of the specified drawable and define the origin of the first char- 
acter. 



items 



Specifies a pointer to an array of text items. 



nitems 



Specifies the number of text items in the array. 



The XDrawTextl6 function is similar to XDrawText except that it uses 2-byte or 
16-bit characters. Both functions allow complex spacing and font shifts between 
counted strings. 

Each text item is processed in turn. A font member other than None in an item 
causes the font to be stored in the GC and used for subsequent text. A text ele- 
ment delta specifies an additional change in the position along the x axis before 
the string is drawn. The delta is always added to the character origin and is not 
dependent on any characteristics of the font. Each character image, as defined 
by the font in the GC, is treated as an additional mask for a fill operation on the 
drawable. The drawable is modified only where the font character has a bit set 
to 1. If a text item generates a BadFont error, the previous text items may have 
been drawn. 

For fonts defined with linear indexing rather than 2-byte matrix indexing, each 
XChar2b structure is interpreted as a 16-bit number with bytel as the most- 
significant byte. 

Both functions use these GC components: function, plane-mask, fill-style, font, 
subwindow-mode, clip-x-origin, clip-y-origin, and clip-mask. They also use 
these GC mode-dependent components: foreground, background, tile, stipple, 
tile-stipple-x-origin, and tile-stipple-y-origin. 

XDrawText and XDrawTextl6 can generate BadDrawable, BadFont, BadGC, and 
BadMatch errors. 
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Drawing Text Characters 

To draw 8-bit characters in a given drawable, use XDrawString. 

XDrawString (</is^2ay, d, gc, x, y, string, length) 
Display ^display; 
Drawable d; 
GC gc; 
int X, y; 
char ^string; 
int length; 



display Specifies the connection to the XwiN server. 

d Specifies the drawable. 

gc Specifies the GC. 

X 

y Specify the x and y coordinates, which are relative to the origin 

of the specified drawable and define the origin of the first char- 
acter. 

string Specifies the character string. 

length Specifies the number of characters in the string argument. 



To draw 2-byte characters in a given drawable, use XDrawStringl6. 

XDrai«Strin9l6 (<iisf?/ay, d, gc, x, y, string, length) 
Display ^display; 
Drawable d; 
GCgc; 
int X, y; 

XChar2b ^string; 
int length; 

display Specifies the connection to the XwiN server. 

d Specifies the drawable. 
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gc Spedfies the GC 

X 

y Specify the x and y coordinates, which are relative to the origin 

of the specified drawable and define the origin of the first char- 
acter. 

string Specifies the character string. 

length Specifies the number of characters in the string argument. 

Each character image, as defined by the font in the GC, is treated as an addi- 
tional mask for a fill operation on the drawable. The drawable is modified only 
where the font character has a bit set to 1. For fonts defined with 2-byte matrix 
indexing and used with XDrawStringl6, each byte is used as a byte2 with a 
bytel of zero. 

Both functions use these GC components: function, plane-mask, fill-style, font, 
subwindow-mode, clip-x-origin, clip-y-origin, and clip-mask. They also use 
these GC mode-dependent components: foreground, background, tile, stipple, 
tile-stipple-x-origin, and tile-stipple-y-origin. 

XDrawString and XDrawStringl6 can generate BadDrawable, BadGC, and Bad- 
Match errors. 



Drawing Image Text Characters 

Some applications, in particular terminal emulators, need to print inmge text in 
which both the foreground and background bits of each character are painted. 
This prevents annoying flicker on many displays. 

To draw 8-bit image text characters in a given drawable, use XDrawlnage- 
String. 

XDrawImageString (iisf^y, d, gc, x, y, string, length) 
Display ^display; 
Drawable d) 
GCgc; 
int X, y; 
char * string; 
int length', 
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display Specifies the connection to the XwiN server. 

d Specifies the drawable. 

gc Specifies the GC 

X 

y Specify the x and y coordinates, which are relative to the origin 

of the specified drawable and define the origin of the first char- 
acter. 

string Specifies the character string. 

length Specifies the number of characters in the string argument. 



To draw 2-byte image text characters in a given drawable, use XDrawImage- 
Stringl6. 

XDrawImageStriiiglS {display, d, gc, x, y, string, length) 
Display ^display; 
Drawable d) 
GCgc; 
int X, y; 

XChar2b ^string; 
int length; 



display Specifies the connection to the XwiN server. 

d Specifies the drawable. 

gc Specifies the GC 

X 

y Specify the x and y coordinates, which are relative to the origin 

of the specified drawable and define the origin of the first char- 
acter. 

string Specifies the character string. 

length Specifies the number of characters in the string argument. 



The XDrawImageStringie function is similar to XDrawIinageString except that 
it uses 2-byte or 16-bit characters. Both functions also use both the foreground 
and background pixels of the GC in the destination. 
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The effect is first to fill a destination rectangle with the background pixel 
defined in the GC and then to paint the text with the foreground pixel. The 
upper-left comer of the filled rectangle is at: 

[x, y - font-aaoent] 

The width is: 

ovorall-width 

The height is: 

font-ascsant -¥ font-descaent 

The overall-width, font-ascent, and font-descent are as would be returned by 
XQueryTextExtents using gc and string. The function and fill-style defined in 
the GC are ignored for these functions. The effective function is GXcopy, and the 
effective fill-style is FillSolid. 

For fonts defined with 2-byte matrix indexing and used with XDrawlmage- 
String, each byte is used as a byte2 with a b3rtel of zero. 

Both functions use these GC components: plane-mask, foreground, background, 
font, subwindow-mode, clip-x-origin, clip-y-origin, and clip-mask. 

XDrawlmageString and XDrawIinageStringl6 can generate BadDrawable, 
BadGC, and BadMatch errors. 
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Xlib provides functions that you can use to transfer images between a client and 
the server. Because the server may require diverse data formats, Xlib provides 
an image object that fully describes the data in memory and that provides for 
basic operations on that data. You should reference the data through the image 
object rather than referencing the data directly. However, some implementa- 
tions of the Xlib library may efficiently deal with frequently used data formats 
by replacing functions in the procedure vector with special case functions. Sup- 
ported operations include destroying the image, getting a pixel, storing a pixel, 
extracting a subimagQ of an image, and adding a constant to an image (see 
Chapter 10). 

All the image manipulation functions discussed in this section make use of the 
XIniage data structure, which describes an image as it exists in the client" s 
memory. 



Graphics Functions 



6-47 



Transferring Images between Client and Server 



t:^padef struct ^XlaagB { 
int width, heigbt; 
int xoffaet; 
int foxnat; 
char *data; 
int bytej>xder; 
int bitnapjunit; 
int bitflu^JditjDxdar; 
int bitmi^pjpad; 
int depth; 
int byte8_perj.ine; 
int bit8_perjpixial; 
tinsignad long rsdjoaalc; 
iinsigned long greenjnask; 
unsigned long bluejnask; 
char *obdata; 
struct funcs { 



/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 



/* 



size of image */ 

nunber of pixels offset in X direction */ 

XYBitnap, XXPixnap, ZPixmap */ 

pointer to image data */ 

data byte order, LSBFirst, MSBFirst */ 

quant, of soanline 8, 16, 32 V 

LSBFirst, MSBFirst */ 

8, 16, 32 eitber XX or ZPixnap */ 

depth of image */ 

accelerator to next scanline */ 

bits per pixsl (ZPixmap) */ 

bits in z arrangement */ 



hook for the object routines to hang on */ 
image manipulation routines */ 



struct _XImage * (*create_image) () ; 
int (*destroy_image) () ; 
unsigned long (*get_|>ixBl) () ; 
int (*putjpixel) (); 
struct _XImage * (*sub_image) () ; 
int (*addjpixel) () ; 



You may request that some of the members (for example, height, width, and 
xoff set) be changed when the image is sent to the server. That is, you may send 
a subset of the image. Other members (for example, byte_order, bitmap_unit, 
and so forth) are characteristics of both the image and the server. If these 
members differ between the image and the server, XPutlraage makes the 
appropriate conversions. The first byte of the first scanline of plane n is located 
at the address (data + (n * height * bytes j)erjine)). 

To combine an image in memory with a rectangle of a drawable on the display, 
use XPut Image. 
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lXButJmg& (display, d, gc, image, srcjc, srcjf, destjc, destjf, width, height) 
Oisplay ^display; 
Drawable d) 
GCgc, 

Xlmage *intage; 
int srcjc, srcjf; 
int destjc, destjy; 
unsigned int width, height; 

display Specifies the connection to the XwiN server. 

d Specifies the drawable. 

gc Specifies the GC. 

image Specifies the image you want combined with the rectangle. 

srcjc Specifies the offset in X from the left edge of the image defined 

by the XIraage data structure. 

srcj^ Specifies the offset in Y from the top edge of the image defined 

by the Xlmage data structure. 

destjx 

destjf Specify the x and y coordinates, which are relative to the origin 

of the drawable and are the coordinates of the subimage. 

width 

height Specify the width and height of the subimage, which define the 

dimensions of the rectangle. 

The XPutlraage function combines an image in memory with a rectangle of the 
specified drawable. If XYBitniap format is used, the depth must be one, or a 
BadMatch error results. The foreground pixel in the GC defines the source for 
the one bits in the image, and the background pixel defines the source for the 
zero bits. For XYPixraap and ZPixraap, the depth must match the depth of the 
drawable, or a BadMatch error results. The section of the image defined by the 
src^x, srcjr, width, and height arguments is drawn on the specified part of the 
drawable. 

This function uses these GC components: function, plane-n\ask, subwindow- 
mode, clip-x-origin, clip-y-origin, and clip-mask. It also uses these GC mode- 
dependent components: foreground and background. 
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XPutlinage can generate BadDrawable, BadGC, BadMatch, and BadValue errors. 

To return the contents of a rectangle in a given drawable on the display, use 
XGet Image. This function specifically supports rudimentary screen dumps. 

Xlmagie *XGetIiDage {display, d, x, y, width, height, pUmejnask, format) 
Display ^display; 
Drawable d; 
int X, y; 

unsigned int width, height; 
long plane jnask; 
int format; 

display Specifies the connection to the XwiN server. 

d Specifies the drawable. 

X 

y Specify the x and y coordinates, which are relative to the origin 

of the drawable and define the upper-left comer of the rectan- 
gle. 

width 

height Specify the width and height of the subimage, which define the 

dimensions of the rectangle. 

plane jnask Specifies the plane mask. 

format Specifies the format for the image. You can pass XYBitraap, 

XYPixinap, or ZPixnap. 

The XGetlniage function returns a pointer to an Xlinage structure. This struc- 
ture provides you with the contents of the specified rectangle of the drawable in 
the format you specify. If the format argument is XYPixinap, the image contains 
only the bit planes you passed to the plane_mask argument. If the plane_mask 
argument only requests a subset of the planes of the display, the depth of the 
returned image will be the number of planes requested. If the format argument 
is ZPlxmap, XGetlniage returns as zero the bits in all planes not specified in the 
plane_mask argument. The function performs no range checking on the values 
in plane_mask and ignores extraneous bits. 
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XGetlinage returns the depth of the image to the depth member of the Xlinage 
structure. The depth of the image is as specified when the drawable was 
created, except when getting a subset of the planes in XYPixroap format, when 
the depth is given by the number of bits set to 1 in plane_mask. 

If the drawable is a pixmap, the given rectangle must be wholly contained 
within the pixmap, or a BadMatch error results. If the drawable is a window, 
the window must be viewable, and it must be the case that if there were no 
inferiors or overlapping windows, the specified rectangle of the window would 
be fully visible on the screen and wholly contained within the outside edges of 
the window, or a BadMatch error results. Note that the borders of the window 
can be included and read with this request. If the window has backing-store, 
the backing-store contents are returned for regions of the window that are 
obscured by noninferior windows. If the window does not have backing-store, 
the returned contents of such obscured regions are undefined. The returned 
contents of visible regions of inferiors of a different depth than the specified 
window's depth are also undefined. The pointer cursor image is not included 
in the returned contents. 

XGetlinage can generate BadDrawable, BadMatch, and BadValue errors. 

To copy the contents of a rectangle on the display to a location within a preex- 
isting image structure, use XGetSublinage. 

XLnagB *X5etSubIinage {display, d, x, y, width, height, plane jnask, format, destjmage, destjc. 



destjy) 
Display ^display; 
Drawable d; 
int X, y; 

unsigned int width, height; 
unsigned long plane jnask; 
int format; 
Xlmage *destjmage; 
int destjc, destjf; 



display 
d 



Specifies the connection to the XWIN server. 
Specifies the drawable. 



Graphics 



Functions 



6-51 



Transferring Images between Client and Server 



X 



y 



Spedfy the x and y coordinates, which are relative to the origin 
of the drawable and define the upper-left comer of the rectan- 
gle. 



mdth 
height 



Specify the width and height of the subiniage, which define the 
dimensions of the rectangle. 

Specifies the plane mask. 

Specifies the format for the image. You can pass XYBitmap, 
XYPdbanap, or ZPixinap. 

Spedfy the destination image. 



planejnask 
format 



destjmage 

destjc 
destjf 



Spedfy the x and y coordinates, which are relative to the origin 
of the destination rectangle, specify its upper-left comer, and 
determine where the subimage is placed in the destination 
image. 



The »3etSubIniage function updates dest_image with the specified subimage in 
the same manner as XGet Image. If the format argument is XYPixraap, the image 
contains only the bit planes you passed to the plane_mask argument. If the for- 
mat argument is ZPixinap, XGetSublmage returns as zero the bits in all planes 
not specified in the plane mask argument. The function performs no range 
checking on the values in plane__mask and ignores extraneous bits. As a con- 
venience, XGetSublmage returns a pointer to the same Xlmage stracture 
spedfied by destjmage. 

The depth of the destination Xlinage stmcture must be the same as that of the 
drawable. If the specified subimage does not fit at the spedfied location on the 
destination image, the right and bottom edges are clipped. If the drawable is a 
pixmap, the given rectangle must be wholly contained within the pixmap, or a 
BadMatch error results. If the drawable is a window, the window must be 
viewable, and it must be the case that if there were no inferiors or overlapping 
windows, the spedfied rectangle of the window would be fully visible on the 
screen and wholly contained within the outside edges of the window, or a Bad- 
Match error results. If the window has backing-store, then the backing-store 
contents are retumed for regions of the window that are obscured by noninfe- 
rior windows. If the window does not have backing-store, the returned contents 
of such obscured regions are undefined. The retumed contents of visible 
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regions of inferiors of a different depth than the specified window's depth are 
also undefined. 

XGetSublinage can generate BadDrawable, BadGC, BadMatch, and BadValue 
errors. 
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This section discusses how to: 

■ Create a cursor 

■ Change or destroy a cursor 

■ Define the cursor for a window 

Each window can have a different cursor defined for it. Whenever the pointer 
is in a visible window, it is set to the cursor defined for that window. If no cur- 
sor was defined for that window, the cursor is the one defined for the parent 
window. 

From X's perspective, a cursor consists of a cursor source, mask, colors, and a 
hotspot. The mask pixmap determines the shape of the cursor and must be a 
depth of one. The source pixmap must have a depth of one, and the colors 
determine the colors of the source. The hotspot defines the point on the cursor 
that is reported when a pointer event occurs. There may be limitations imposed 
by the hardware on cursors as to size and whether a mask is implemented. 
XQueryBestCursor can be used to find out what sizes are possible. It is 
intended that most standard cursors will be stored as a special font. 

Creating a Cursor 

Xlib provides functions that you can use to create a font, bitmap, or glyph cur- 
sor. 

To create a cursor from a standard font, use XCreateFontCursor. 

tinclude <Xll/curaorfont.h> 

Cursor XCreateFontCursor ((display, s^pe) 
Display ^display; 
unsigned int shape; 

display Specifies the connection to the XwiN server. 

shape Specifies the shape of the cursor. 
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X provides a set of standard cursor shapes in a special font named cursor. 
Applications are encouraged to use this interface for their cursors because the 
font can be custoniized for the individual display type. The shape argument 
specifies which glyph of the standard fonts to use. 

The hotspot comes from the information stored in the cursor font. The initial 
colors of a cursor are a black foreground and a white background (see 
XRecolorCursor). For further information about cursor shapes, see appendix 
B. 

XCreateFontCursor can generate BadAlloc and BadValue errors. 

To create a cursor from two bitmaps, use XCreatePdjonapCursor. 

Cursor 3{Creat«PixDBapCur8or (</tsp2ay, source, mask, foreground jsolor, background jx)lor, x, y) 
Display ^display; 
Pixmap source; 
Pixmap mask; 
XColor * foreground jx>Jor; 
XColor *background_cdor; 
unsigned int x, y; 

display Specifies the connection to the XwiN server. 

source Specifies the shape of the source cursor. 

mask Specifies the cursor's source bits to be displayed or None. 

foreground j:olor 

Specifies the RGB values for the foreground of the source. 

background j:olor 

Specifies the RGB values for the backgrotmd of the source. 

X 

y Specify the x and y coordinates, which indicate the hotspot rela- 

tive to the source's origin. 

The XCreatePixitiapCursor function creates a cursor and returns the cursor ID 
associated with it. The foreground and background RGB values must be 
specified using foreground_color and background_color, even if the XwiN server 
only has a StaticGray or Grayscale screen. The foreground color is used for 
the pixels set to 1 in the source, and the background color is used for the pixels 
set to 0. Both source and mask, if specified, must have depth one (or a 
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BadMatch error results) but can have any root. The mask argument defines the 
shape of the cursor. The pixels set to 1 in the mask define which source pixels 
are displayed, and the pixels set to 0 define which pixels are ignored. If no 
mask is given, all pixels of the source are displayed. The mask, if present, must 
be the same size as the pixmap defined by the source argument, or a BadMatch 
error results. The hotspot must be a point within the source, or a BadMatch 
error results. 

The components of the cursor can be transformed arbitrarily to meet display 
limitations. The pixmaps can be freed immediately if no further explicit refer- 
ences to them are to be made. Subsequent drawing in the source or mask pix- 
map has an undefined effect on the cursor. The XwiN server might or might not 
make a copy of the pixmap. 

XCreatePlxxnapCursor can generate BadAlloc and BadPdbanap errors. 

To create a cursor from font glyphs, use XCreateGlyphCursor. 

Cursor XCreateGlyphCursor (^]s;7lay, source Jont, mask Jont, source jhar, mask^char, 
foreground jxHor, hackgroundjxior) 
Display *dispUnf; 
Font source Jont, mask Jont; 
unsigned int source jMr, mask_char; 
XColor *joregroundjx)lor; 
XColor *backgroundjxlor; 

display specifies the connection to the XwiN server. 

source Jont Specifies the font for the source glyph. 
mask Jont Specifies the font for the mask glyph or None. 
source jhar Specifies the character glyph for the source. 
maskjhar Specifies the glyph character for the mask. 
foreground_color 

Specifies the RGB values for the foreground of the source. 

hackgroundjxior 

Specifies the RGB values for the background of the source. 
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The XCreateGlyphCursor function is similar to XCreatePixroapCursor except 
that the source and mask bitmaps are obtained from the specified font glyphs. 
The source_char must be a defined glyph in source_font, or a BadValue error 
results. If mask font is given, mask_char must be a defined glyph in mask_font, 
or a BadValue error results. The mask_font and character are optional. The 
origins of the source_char and mask_char (if defined) glyphs are positioned 
coincidently and define the hotspot. The source_char and mask_char need not 
have the same bounding box metrics, and there is no restriction on the place- 
ment of the hotspot relative to the bounding boxes. If no mask_char is given, all 
pixels of the source are displayed. You can free the fonts inunediately by 
calling XFreeFont if no further explicit references to them are to be made. 

For 2-byte matrix fonts, the 16-bit value should be formed with the bytel 
member in the most-significant byte and the byte2 member in the least- 
significant byte. 

XCreateGlyphCursor can generate BadAlloc, BadFont, and BadValue errors. 

Changing and Destroying Cursors 

Xlib provides functions that you can use to change the cursor color, destroy the 
cursor, and determine the best cursor size. 

To change the color of a given cursor, use XRecolorCursor. 

XRecoloxCursor {display, cursor, foreground j:olor, background jxilor) 
Display ^display; 
Ctirsor cursor) 

XColor *foreground_color, *hackgroundj:olor; 

display Specifies the connection to the XwiN server. 

cursor Specifies the cursor. 

foregroundj:olor 

Specifies the RGB values for the foreground of the source. 

backgroundj:olor 

Specifies the RGB values for the background of the source. 
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The XRecolorCursor function changes the color of the specified cursor, and if 
the cursor is being displayed on a screen, the change is visible immediately. 

XRecolorCursor can generate a BadCursor error. 

To free (destroy) a given cursor, use XFreeCursor. 

XFreeCursor {display, cursor) 
Display *displ«y; 
Cursor cursor; 

display Specifies the connection to the XwiN server. 

cursor Specifies the cursor. 

The XFreeCursor function deletes the association between the cursor resource 
ID and the specified cursor. The cursor storage is freed when no other resource 
references it. The specified cursor ID should not be referred to again. 

XFreeCursor can generate a BadCursor error. 

To determine useful cursor sizes, use 3K2ueryBestCursor. 

status yQa»r^BBatCaraor {display, d, width, height, width jetum, heightjetum) 
Display ^display; 
Drawable d-, 

unsigned int width, height) 

unsigned int *widthjretum, *heightjretum; 

display Specifies the connection to the XwiN server. 

d Specifies the drawable, which indicates the screen. 

xvidth 

height Specify the width and height of the cursor that you want the 

size information for. 

xvidthjeturn 

hdghtjreturn Return the best width and height that is closest to the specified 
width and height. 

Some displays allow larger cursors than other displays. The XQueryBestCursor 
function provides a way to find out what size cursors are actually possible on 
the display. 
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It returns the largest size that can be displayed. Applications should be 
prepared to use smaller cursors on displays that cannot support large ones. 

XQueryBestCursor can generate a BadDrawable error. 

Defining tlie Cursor 

Xlib provides functions that you can use to define or undefine the cursor that 
should be displayed in a window. 

To define which cursor will be used in a window, use XDefineCursor. 

XDefizieCursor {display, w, cursor) 
Display ^display; 
Window w; 
Cursor cursor; 

display Specifies the connection to the XwiN server. 

w Specifies the window. 

cursor Specifies the cursor that is to be displayed or None. 

If a cursor is set, it will be used when the pointer is in the window. If the cur- 
sor is N6ne, it is equivalent to XUndefineCursor. 

XDefineCursor can generate BadCursor and BadWlndow errors. 

To undefine the cursor in a given window, use XUndeflneCu^rsor. 

XOa^tijneCaraor {display, w) 
Display *display; 
Window w; 

display Specifies the connection to the XwiN server. 

w Specifies the window. 
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The xandef ineCursor undoes the effect of a previous XDef ineCursor for this 
window. When the pointer is in the window, the parent's cursor will now be 
used. On the root window, the default cursor is restored. 

XUndef ineCursor can generate a BadWindow error. 
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Although it is difficult to categorize functions as application only or window 
manager only, the functions in this chapter are most often used by window 
managers. It is not expected that these functions will be used by most applica- 
tion programs. You can use the Xlib window manager functions to: 

■ Change the parent of a window 

■ Control the lifetime of a window 

■ Determine resident colormaps 

■ Grab the pointer 

■ Grab the keyboard 

■ Grab the server 

■ Control event processing 

■ Manipulate the keyboard and pointer settings 

■ Control the screen saver 

■ Control host access 
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To change a window's parent to another window on the same screen, use 
XReparentWindow. There is no way to move a window between screens. 

XReparentWindow (iis;72ay, w, parent, x, y) 
Display ^display; 
Window w; 
Window parent; 
int X, y; 

display Specifies the connection to the XwiN server. 

XV Specifies the window. 

parent Specifies the parent window. 

X 

y Specify the x and y coordinates of the position in the new 

parent window. 

If the specified window is mapped, XReparentWindow automatically performs 
an UninapWindow request on it, removes it from its current position in the hierar- 
chy, and inserts it as the child of the specified parent. The window is placed in 
the stacking order on top with respect to sibling windows. 

After reparenting the specified window, XReparentWindow causes the XwiN 
server to generate a ReparentNotify event. The override_redirect member 
returned in this event is set to the window's corresponding attribute. Window 
manager clients usually should ignore this window if this member is set to 
True. Finally, if the specified window was originally mapped, the XwiN server 
automatically performs a MapWindow request on it. 

The XwiN server perfomns normal exposure processing on formerly obscured 
windows. The XwiN server might not generate Expose events for regions from 
the initial UnnapWindow request that are immediately obscured by the final 
MapWindow request. A BadMatch error results if: 

■ The new parent window is not on the same screen as the old parent win- 
dow. 

■ The new parent window is the specified window or an inferior of the 
specified window. 
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■ The specified window has a ParentRelative background, and the new 
parent window is not the same depth as the specified window. 

XReparentWindow can generate BadMatch and BadWlndow errors. 
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The save-set of a client is a list of other clients' windows that, if they are inferi- 
ors of one of the client's windows at connection close, should not be destroyed 
and should be remapped if they are unmapped. For further information about 
close-connection processing, see "X Server Connection Close Operations" in 
Chapter 2. To allow an application's window to survive when a window 
manager that has reparented a window fails, Xlib provides the save-set func- 
tions that you can use to control the longevity of subwindows that are normally 
destroyed when the parent is destroyed. For example, a window manager that 
wants to add decoration to a window by adding a frame nught reparent an 
application's window. When the frame is destroyed, the application's window 
should not be destroyed but be returned to its previous place in the window 
hierarchy. 

The XwiN server automatically removes windows from the save-set when they 
are destroyed. 

To add or remove a window from the client's save-set, use XChangeSaveSet. 

XChangeSaveSet {display, w, changejnode) 
Display * display; 
Window w; 
int changejnode; 

display Specifies the connection to the XwiN server. 

w Specifies the window that you want to add to or delete from the 

client's save-set. 

changejnode Specifies the mode. You can pass SetModelnsert or 
SetModeDelete . 

Depending on the specified mode, XChangeSaveSet either inserts or deletes the 
specified window from the client's save-set. The specified window must have 
been created by some other client, or a BadMatch error results. 

XChangeSaveSet can generate BadMatch, BadValue, and BadWindow errors. 

To add a window to the dienf s save-set, use XAddToSaveSet. 

XAddToSaveSet {display, w) 
Display ^display; 
Window w; 
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display Specifies the connection to the XwiN server. 

w Specifies the window that you want to add to the client's save- 

set. 

The XAddToSaveSet function adds the specified window to the client's save-set. 
The specified window must have been created by some other client, or a Bad- 
Match error results. 

XAddToSaveSet can generate BadMatch and BadWindow errors. 

To remove a window from the client's save-set, use XReraoveFroinSaveSet. 

XRenovaFromSaveSet (display, w) 
Display * display, 
Window w; 

display Specifies the connection to the XwiN server. 

w Specifies the window that you want to delete from the client's 

save-set 

The XReraoveFrOTiSaveSet function removes the specified window from the 
client's save-set. The specified window must have been created by some other 
client, or a BadMatch error results. 

XReinoveFroinSaveSet can generate BadMatch and BadWindow errors. 
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Xlib provides functions that you can use to install a colormap, uninstall a color- 
map, and obtain a list of installed colormaps. 

At any time, there is a subset of the installed maps that is viewed as an ordered 
list and is called the required list. The length of the required list is at most M, 
where M is the minimum number of installed colormaps specified for the screen 
in the connection setup. The required list is maintained as follows. When a 
colormap is specified to XInstallColonnap, it is added to the head of the list; 
the list is truncated at the tail, if necessary, to keep its length to at most M. 
When a colormap is specified to XUninstallColorniap and it is in the required 
list, it is removed from the list. A colormap is not added to the required list 
when it is implicitly installed by the XWIN server, and the XWIN server cannot 
implicitly uninstall a colormap that is in the required list. 

To install a colormap, use XInstallColonnap. 

XlnatallColonsap (display, colormap) 
Display *display; 
Colormap colormap; 

display Specifies the connection to the XwiN server. 

colormap Specifies the colormap. 

The XInstallColonnap function installs the specified colormap for its associ- 
ated screen. All windows associated with this colormap immediately display 
with true colors. You associated the windows with this colormap when you 
created them by calling XCreateWindow, XCreateSiinpleWindow, XChangeWin- 
dowAttributes, or XSetWindowColonnap. 

If the specified colormap is not already an installed colormap, the XwiN server 
generates a ColonnapNotify event on each window that has that colormap. In 
addition, for every other colormap that is installed as a result of a call to XIn- 
stallColonnap, the XwiN server generates a ColonnapNotify event on each 
window that has that colormap. 

XInstallColonnap can generate a BadColor error. 

To uninstall a colormap, use XUninstallColomap. 
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XUhinstallColo£map( (display, colormap) 
Display ^display; 
Colormap colormap; 



display 
colormap 



Specifies the connection to the XwiN server. 
Specifies the colormap. 



The XUninstallColormap function removes the specified colormap from the 
required list for its screen. As a result, the specified colormap might be unin- 
stalled, and the XwiN server might implicitly install or uninstall additional color- 
maps. Which colormaps get installed or uninstalled is server-dependent except 
that the required list must remain installed. 

If the specified colormap becomes uninstalled, the XwiN server generates a 
ColonnapNotify event on each window that has that colormap. In addition, 
for every other colormap that is installed or uninstalled as a result of a call to 
XUninstallColoritiap, the XwiN server generates a ColormapNotify event on 
each window that has that colormap. 

XUninstallColormap can generate a BadColor error. 

To obtain a list of the currently installed colormaps for a given screen, use 
XList InstalledColormaps . 

Colormap *XListInstalleGlColO£inaps ((display, w, numjetwm) 
Display ^display; 
Window w; 
int *num_fetum; 

display Specifies the connection to the XwiN server. 

w Specifies the window that determines the screen. 

numjeturn Returns the number of currently installed colormaps. 

The XListlnstalledColonnaps function returns a list of the currently installed 
colormaps for the screen of the specified window. The order of the colormaps 
in the list is not significant and is no explicit indication of the required list. 
When the allocated list is no longer needed, free it by using XFree. 

XListlnstalledColonnaps can generate a BadWindow error. 
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Xlib provides functions that you can use to control input from the pointer, 
which usually is a mouse. Window managers most often use these facilities to 
implement certain styles of user interfaces. Some toolkits also need to use these 
facilities for special purposes. 

Usually, as soon as keyboard and mouse events occur, the XwiN server delivers 
them to the appropriate client, which is determined by the window and input 
focus. The XwiN server provides sufficient control over event delivery to allow 
window managers to support mouse ahead and various other styles of user 
interface. Many of these user interfaces depend upon synchronous delivery of 
events. The delivery of pointer and keyboard events can be controlled 
independently. 

When mouse buttons or keyboard keys are grabbed, events will be sent to the 
grabbing client rather than the normal client who would have received the 
event. If the keyboard or pointer is in asynchronous mode, further mouse and 
keyboard events will continue to be processed. If the keyboard or pointer is in 
synchronous mode, no further events are processed until the grabbing client 
allows them (see XAllowEvents). The keyboard or pointer is considered frozen 
during this interval. The event that triggered the grab can also be replayed. 

Note that the logical state of a device (as seen by client applications) may lag 
the physical state if device event processing is frozen. 

There are two kinds of grabs: active and passive. An active grab occurs when a 
single client grabs the keyboard and/or pointer explicitly (see XGrabPointer 
and XGrabKeyboard). A passive grab occurs when clients grab a particular key- 
board key or pointer button in a window, and the grab will activate when the 
key or button is actually pressed. Passive grabs are convenient for implement- 
ing reliable pop-up menus. For example, you can guarantee that the pop-up is 
mapped before the up pointer button event occurs by grabbing a button 
requesting synchronous behavior. The down event will trigger the grab and 
freeze further processing of pointer events until you have the chance to map the 
pop-up window. You can then allow further event processing. The up event 
will then be correctly processed relative to the pop-up window. 

For many operations, there are functions that take a time argument. The XwiN 
server includes a timestamp in various events. One special time, called 
CurrentTime, represents the current server time. The XwiN server maintains 
the time when the input focus was last changed, when the keyboard was last 
grabbed, when the pointer was last grabbed, or when a selection was last 
changed. Your application may be slow reacting to an event. You often need 
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some way to specify that your request should not occur if another application 
has in the meanwhile taken control of the keyboard, pointer, or selection. By 
providing the timestamp from the event in the request, you can arrange that the 
operation not take effect if someone else has performed an operation in the 
meanwhile. 

A timestamp is a time value, expressed in milliseconds. It typically is the time 
since the last server reset. Timestamp values wrap around (after about 49.7 
days). The server, given its current time is represented by timestamp T, always 
interprets timestamps from clients by treating half of the timestamp space as 
being later in time ttian T. One timestamp value, named CurrentTiine, is never 
generated by the server. This value is reserved for use in requests to represent 
the current server time. 

For many functions in this section, you pass pointer event mask bits. The valid 
pointer event mask bits are: ButtonPress^fesk, ButtonReleaseMask, EnterWin- 
dowMask, LeaveWindowMask, PointerMotionMask, PointezMotionHintMask, 
ButtonlMotionMask, Button2MDtionMask, ButtonSMotionMask, 
Button4MotionMask, ButtonSMotionMask, ButtonMotionMask, and Key- 
MapStateMask. For other functions in this section, you pass keymask bits. The 
valid ke)miask bits are: ShiftMask, LockMask, ControIMask, ModlMask, 
Mod2Mask, ModSMask, Mod4Mask, and ModSMask. 

To grab the pointer, use XGrabPointer. 



int XSrabPointer (itsp^oy, grabjoindow, owner jvents, event jnask, pointerjnode, 
keyboard jnode, confine Jo, cursor, time) 
Display Hisplay; 
Window grabjuindow; 
Bool owner jvents; 
unsigned int event jnask; 
int pointerjnode, keyboardjnode; 
Window confine Jo; 
Cursor cursor; 
Time time; 

display Specifies the connection to the XwiN server. 
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grabjvindow Specifies the grab window. 

owner jvents Spedfies a Boolean value that indicates whether the pointer 
events are to be reported as usual or reported with respect to 
the grab window if selected by the event mask. 

event jnask Specifies which pointer events are reported to the client. The 

mask is the bitwise inclusive OR of the valid pointer event mask 
bits. 

pointer jnode Specifies further processing of pointer events. You can pass 
GrabModeSync or GrabMcxleAsync. 

keyboardjnode Spedfies further processing of keyboard events. You can pass 
GrabModeSync or GrabModeAsync. 

confine Jo Spedfies the window to confine the pointer in or None. 

cursor Spedfies the cursor that is to be displayed during the grab or 

None. 

time Spedfies the time. You can pass dther a timestamp or Current- 

Time. 



The XGrabPointer function actively grabs control of the pointer and returns 
GrabSuccess if the grab was successful. Further pointer events are reported 
only to the grabbing client. XGrabPointer overrides any active pointer grab by 
this client. If owner_events is False, all generated pointer events are reported 
with respect to grab_window and are reported only if selected by event_mask. 
If owner_events is True and if a generated pointer event would normally be 
reported to this dient, it is reported as usual. Otherwise, the event is reported 
with respect to the grab_window and is reported only if selected by 
event_mask. For either value of owner_events, unreported events are discarded. 

If the pointer_mode is GrabModeAsync, pointer event processing continues as 
usual. If the pointer is currently frozen by this client, the processing of events 
for the pointer is resumed. If the pointer jnode is GrabModeSync, the state of 
the pointer, as seen by client applications, appears to freeze, and the XWIN 
server generates no further pointer events until the grabbing client calls XAl- 
lowEvents or until the pointer grab is released. Actual pointer changes are not 
lost while the pointer is frozen; they are simply queued in the server for later 
processing. 
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If the keyboard_mode is Grahl^todeAsync, keyboard event processing is unaf- 
fected by activation of the grab. If the keyboard_mode is GrabModeSync, the 
state of the keyboard, as seen by client applications, appears to freeze, and the 
XWIN server generates no further keyboard events until the grabbing client calls 
XAllowEvents or until the pointer grab is released. Actual keyboard changes 
are not lost while the pointer is frozen; they are simply queued in the server for 
later processing. 

If a cursor is specified, it is displayed regardless of what window the pointer is 
in. If None is specified, the nonnal cursor for that window is displayed when 
the pointer is in grab_window or one of its subwindows; otherwise, the cursor 
for grab_window is displayed. 

If a confine_to window is specified, the pointer is restricted to stay contained in 
that window. The confine_to window need have no relationship to the 
grab_window. If the jx)inter is not initially in the confine_to window, it is 
warped automatically to the closest edge just before the grab activates and 
enter/leave events are generated as usual. If the confine_to window is subse- 
quently reconfigured, the pointer is warped automatically, as necessary, to keep 
it contained in the window. 

The time argument allows you to avoid certain circumstances that come up if 
applications take a long time to respond or if there are long network delays. 
Consider a situation where you have two applications, both of which normally 
grab the pointer when clicked on. If both applications specify the timestamp 
from the event, the second application may wake up faster and successfully 
grab the pointer before the first application. The first application then will get 
an indication that the other application grabbed the pointer before its request 
was processed. 

XGrabPointer generates EnterNotify and LeaveNotify events. 

Either if grab_window or confine_to window is not viewable or if the confine_to 
window lies completely outside the boundaries of the root window, XGrab- 
Pointer fails and returns GrabNotViewable. If the pointer is actively grabbed 
by some other client, it fails and returns AlreadyGrabbed. If the pointer is 
frozen by an active grab of another client, it fails and returns GrabFrozen. If 
the specified time is earlier than the last-pointer-grab time or later than the 
current XwiN server time, it fails and returns GrablnvalidTime. Otherwise, the 
last-pointer-grab time is set to the specified time ( CurrentTime is replaced by 
the current XwiN server time). 
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XGrabPointer can generate BadCursor, BadValue, and BadWindow errors. 
To ungrab the pointer, use XUngrabPointer. 



xahgrabPointer((/is;7ikiy, time) 
Display ^display; 
Time time; 

display Specifies the connection to the XWIN server. 

time Specifies the time. You can pass either a timestamp or Current- 

Time. 

The XUngrabPointer function releases the pointer and any queued events if 
this client has actively grabbed the pointer from XGrabPointer, XGrabButton, 
or from a normal button press. XUngrabPointer does not release the pointer if 
the specified time is earlier than the last-pointer-grab time or is later than the 
current XwiN server time. It also generates EnterNotify and LeaveNotify 
events. The XwiN server performs an UngrabPointer request automatically if 
the event window or confine_to window for an active pointer grab becomes not 
viewable or if window reconfiguration causes the confine_to window to lie com- 
pletely outside the boundaries of the root window. 

To change an active pointer grab, use XChangeActivePointerGrab. 



XChangeActivaPointerGrab (display, event jnask, cursor, time) 
Display ^display; 
unsigned int event jnask; 
Cursor cursor; 
Time time; 

display Specifies the connection to the XwiN server. 

event jnask Specifies which pointer events are reported to the client The 

mask is the bitwise inclusive OR of the valid pointer event mask 
bits. 
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cursor Specifies the cursor that is to be displayed or None. 

time Specifies the time. You can pass either a timestamp or Current- 

Tine. 

The XChangeActivePointerGrab function changes the specified dynamic 
parameters if the pointer is actively grabbed by the client and if the specified 
time is no earlier than the last-pointer-grab time and no later than the current 
XwiN server time. This function has no effect on the passive parameters of a 
XGrabButton. The interpretation of event^mask and cursor is the same as 
described in XGrabPointer. 

XChangeActivePointerGrab can generate BadCursor and BadValue errors. 
To grab a pointer button, use XGrabButton. 



XGrabButton {display, button, modifiers, grabjoindow, owner jvents, event jnask, 
pointer jnode, keyboard jnode, confine Jo, cursor) 
Display ^display; 
unsigned int button; 
unsigned int modifiers; 
Window grabjoindow; 
Bool owner jvents; 
unsigned int event jnask; 
int pointer jnode, keyboardjnode; 
Window confine Jo; 
Cursor cursor; 



display Specifies the connection to the XwiN server. 

button Specifies the pointer button that is to be grabbed or AnyButton. 

modifiers Specifies the set of keymasks or AnyModif ier. The mask is the 

bitwise inclusive OR of the valid keymask bits. 

grabjmndow Specifies the grab window. 

owner jvents Specifies a Boolean value that indicates whether the pointer 
events are to be reported as usual or reported with respect to 
the grab window if selected by the event mask. 
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event jnask Specifies which pointer events are reported to the client. The 

mask is the bitwise inclusive OR of the valid pointer event mask 
bits. 

pointerjnode Specifies further processing of pointer events. You can pass 
GrabMcxieSync or GrabMcxieAsync. 

keyboardjnode Specifies further processing of keyboard events. You can pass 
GrabModeSync or GrabMcxieAsync. 

confine Jo Specifies the window to confine the pointer in or None. 

cursor Specifies the cursor that is to be displayed or None. 

The XGrabButton function establishes a passive grab. In the future, the pointer 
is actively grabbed (as for XGrabPointer), the last-pointer-grab time is set to 
the time at which the button was pressed (as transmitted in the ButtonPress 
event), and the ButtonPress event is reported if all of the following conditions 
are true: 

■ The pointer is not grabbed, and the specified button is logically pressed 
when the specified modifier keys are logically down, and no other buttons 
or modifier keys are logically down. 

■ The grab__window contains the pointer. 

■ The confine_to window (if any) is viewable. 

■ A passive grab on the same button/key combination does not exist on 
any ancestor of grab_window. 



The interpretation of the remaining arguments is as for XGrabPointer. The 
active grab is terminated automatically when the logical state of the pointer has 
all buttons released (independent of the state of the logical modifier keys). 

Note that the logical state of a device (as seen by client applications) may lag 
the physical state if device event processing is frozen. 

This request overrides all previous grabs by the same client on the same 
button/key combinations on the same window. A modifiers of AnyMcxiif ier is 
equivalent to issuing the grab request for all possible modifier combinations 
(including the combination of no modifiers). It is not required that all modifiers 
specified have currently assigned KeyCodes. A button of AnyButton is 
equivalent to issuing the request for all possible buttons. Otherwise, it is not 
required that the specified button currently be assigned to a physical button. 
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If some other client has already issued a XGrabButton with the same 
button/key combination on the same window, a BadAccess error results. 
When using AnyModif ier or AnyButton, the request fails completely, and a 
BadAccess error results (no grabs are established) if there is a conflicting grab 
for any combination. XGrabButton has no effect on an active grab. 

XGrabButton can generate BadCursor, BadValue, and BadWindow errors. 

To ungrab a pointer button, use XUngrabButton. 



XUngrahButton (<iisp/fly, button, modifiers, grabjuindow) 
Display ^display; 
unsigned int button; 
unsigned int modifiers; 
Window grabjoindow; 

display Specifies the connection to the XwiN server. 

button Specifies the pointer button that is to be released or AnyButton. 

modifiers Specifies the set of keymasks or AnyModif ier. The mask is the 

bitwise inclusive OR of the valid keymask bits. 

grabjmndow Specifies the grab window. 

The XUngrabButton function releases the passive button/key combination on 
the specified window if it was grabbed by this client A modifiers of AnyModif- 
ier is equivalent to issuing the ungrab request for all possible modifier combi- 
nations, including the combination of no modifiers. A button of AnyButton is 
equivalent to issuing the request for all possible buttons. XUngrabButton has 
no effect on an active grab. 

XUngrabButton can generate BadValue and BadWindow errors. 
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Xlib provides functions that you can use to grab or ungrab the keyboard as well 
as allow events. 

For many functions in this section, you pass keymask bits. The valid keymask 
bits are: Shi£tMask, LockMask, ControlMask, ModlMask, Mod2Mask, ModSMask, 
Mod4Mask, and ModSMask. 

To grab the keyboard, use XGrabKeyboard. 

int YGrailbKByboard {display, grabjoindow, ovmerjvents, pointer jnode, keyboard jnode, time) 
Display *display; 
Window grabjoindow; 
Bool oumerjvents) 
int pointer jnode, heyboardjnode; 
Time time; 

display Specifies the connection to the XwiN server. 

grabjvindow Specifies the grab window. 

owner jvents Specifies a Boolean value that indicates whether the pointer 
events are to be reported as usual or reported with respect to 
the grab window if selected by the event mask. 

pointer jnode Specifies further processing of pointer events. You can pass 
GrabMbdeSync or GrabModeAsync. 

keyboardjnode Specifies further processing of keyboard events. You can pass 
GrabModeSync or GrabMcxieAsync. 

time Specifies the time. You can pass either a timestamp or Current- 

Time. 

The XGrabKeyboard function actively grabs control of the keyboard and gen- 
erates Focusin and FocusOut events. Further key events are reported only to 
the grabbing client. XGrabKeyboard overrides any active keyboard grab by this 
client. If owner_events is False, all generated key events are reported with 
respect to grab_window. If owner_events is True and if a generated key event 
would normally be reported to this client, it is reported normally; otherwise, the 
event is reported with respect to the grab^window. Both KeyPress and 
KeyRelease events are always reported, independent of any event selection 
made by the client. 
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If the keyboard^mcxie argument is GrabModeAsync, keyboard event processing 
continues as usual. If the keyboard is currently frozen by this client, then pro- 
cessing of keyboard events is resumed. If the keyboard mode argument is 
GrahMcxieSync, the state of the keyboard (as seen by client applications) appears 
to freeze, and the XwiN server generates no further keyboard events until the 
grabbing client issues a releasing XAllowEvents call or until the keyboard grab 
is released. Actual keyboard changes are not lost while the keyboard is frozen; 
they are simply queued in the server for later processing. 

If pointer_mode is GrabModeAsync, pointer event processing is unaffected by 
activation of the grab. If pointer mode is GrabModeSync, the state of the pointer 
(as seen by client applications) appears to freeze, and the XwiN server generates 
no further pointer events until the grabbing client issues a releasing XAl- 
lowEvents call or until the keyboard grab is released. Actual pointer changes 
are not lost while the pointer is frozen; they are simply queued in the server for 
later processing. 

If the keyboard is actively grabbed by some other client, XGrabKeyboard fails 
and returns AlreadyGrabbed. If grab window is not viewable, it fails and 
returns GrabNotViewable. If the keyboard is frozen by an active grab of 
another client, it fails and returns GrabFrozen. If the specified time is earlier 
than the last-keyboard-grab time or later than the current XwiN server time, it 
fails and returns GrablnvalidTime. Otherwise, the last-keyboard-grab time is 
set to the specified time ( CurrentTiine is replaced by the current XwiN server 
time). 

XGrabKeyboard can generate BadValue and BadWindow errors. 
To ungrab the keyboard, use XUngrabKeyboard. 

XUi:^rabKa:^x>ard ( display, time) 
Display ^display; 
Time time; 

display Specifies the connection to the XwiN server. 

time Specifies the time. You can pass either a timestamp or Current- 

Time. 

The XUngrabKeyboard function releases the keyboard and any queued events if 
this client has it actively grabbed from either XGrabKeyboard or XGrabKey. 
XUngrabKeyboard does not release the keyboard and any queued events if the 
specified time is earlier than the last-keyboard-grab time or is later than the 
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current XwiN server time. It also generates Focusin and FocusOut events. The 
XwiN server automatically performs an UngrabKeyboard request if the event 
window for an active keyboard grab becomes not viewable. 

To passively grab a single key of the keyboard, use XGrabK^y. 

yGrabKey {displajf, keycode, modifiers, gnibjoindaw, owner jvents, pointer jnode, 
keyhoardjnode) 
Display *dispUiy; 
int keycode; 

unsigned int modifiers; 
Window graibjoindow; 
Bool owner _eoents; 
int pointer jnode, keyboardjnode; 

display Specifies the connection to the XwiN server. 

keycode Specifies the KeyCode or AnyKey. 

modifiers Specifies the set of keymasks or An:^fodif ier. The mask is the 

bitwise inclusive OR of the valid keymask bits. 

grabjvindow Specifies the grab window. 

owner jvents Specifies a Boolean value that indicates whether the pointer 
events are to be reported as usual or reported with respect to 
the grab window if selected by the event mask. 

pointer jnode Specifies further processing of pointer events. You can pass 
GrabMcxieSync or GrabModeAsync. 

keyboardjnode Specifies further processing of keyboard events. You can pass 
GrabModeSync or GrabModeAsync. 

The XGrabKey function establishes a passive grab on the keyboard. In the 
future, the keyboard is actively grabbed (as for XGrabKeyboard), the last- 
keyboard-grab time is set to the time at which the key was pressed (as transmit- 
ted in the KeyPress event), and the KfeyPress event is reported if all of the fol- 
lowing conditions are true: 

■ The keyboard is not grabbed and the specified key (which can itself be a 
modifier key) is logically pressed when the specified modifier keys are 
logically down, and no other modifier keys are logically down. 
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■ Either the grab^window is an ancestor of (or is) the focus window, or the 
grab^window is a descendant of the focus window and contains the 
pointer. 

■ A passive grab on the same key combination does not exist on any ances- 
tor of grab_window. 

The interpretation of the remaining arguments is as for XGrabKeyboard. The 
active grab is terminated automatically when the logical state of the keyboard 
has the specified key released (independent of the logical state of the modifier 
keys). 

Note that the logical state of a device (as seen by client applications) may lag 
the physical state if device event processing is frozen. 

A modifiers argument of AnyMcxiif ier is equivalent to issuing the request for 
all possible modifier combinations (including the combination of no modifiers). 
It is not required that all modifiers specified have currently assigned KeyCodes. 
A keycode argument of AnyKey is equivalent to issuing the request for all possi- 
ble KeyCodes. Otherwise, the specified keycode must be in the range specified 
by min_keycode and max_keycode in the connection setup, or a BadValue error 
results. 

If some other client has issued a XGrabKey with the same key combination on 
the same window, a BadAccess error results. When using AnyModif ier or 
AnyKey, the request fails completely, and a BadAccess error results (no grabs 
are established) if there is a conflicting grab for any combination. 

XGrabKey can generate BadAccess, BadValue, and BadWindow errors. 

To ungrab a key, use XUngrabKey. 



XOiigrabl^y {dispUof, keycode, modifiers, grabjoindow) 
Display ^display; 
int keycode; 

unsigned int modifiers; 
Window grabjuindow; 

display Specifies the connection to the XwiN server. 
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keycode Specifies the KeyCode or AnyRey. 

modifiers Specifies the set of ke}niiasks or AnyModif ier. The mask is the 

bitwise inclusive OR of the valid keymask bits. 

grabjmndow Specifies the grab window. 

The XUngrabKey function releases the key combination on the specified window 
if it was grabbed by this dient. It has no effect on an active grab. A modifiers 
of AnyModifier is equivalent to issuing the request for all possible modifier 
combinations (including the combination of no modifiers). A keycode argument 
of AnyKey is equivalent to issuing the request for all possible key codes. 

XUngrabKey can generate BadValue and BadWindow errors. 

To allow further events to be processed when the device has been frozen, use 
XAllowEvents. 

X]U.lo«Bv<ant8 {display, event jnode, time) 
Display ^display; 
int event jnode; 
Time thne; 

display Specifies the connection to the XwiN server. 

event jnode Specifies the event mode. You can pass AsyncPointer, Sync- 
Pointer, AsyncKe^x>ard, SyncKeyboard, ReplayPointer, 
ReplayKe]^x>ard/ AsyncBoth, or SyncBoth. 

time Specifies the time. You can pass either a timestamp or Current- 

Time. 

The XAllowEvents function releases some queued events if the client has 
caused a device to freeze. It has no effect if the specified time is earlier than the 
last-grab time of the most recent active grab for the client or if the specified time 
is later than the current XwiN server time. Depending on the event_mode argu- 
ment, the following occurs: 
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AsyncPointer If the pointer is frozen by the client, pointer event pro- 
cessing continues as usual. If the pointer is frozen 
twice by the client on behalf of two separate grabs, 
AsyncPointer thaws for both. AsyncPointer has no 
effect if the pointer is not frozen by the client, but the 
pointer need not be grabbed by the client. 

SyncPointer If the pointer is frozen and actively grabbed by the 

client, pointer event processing continues as usual until 
the next ButtonPress or ButtonRelease event is 
rep)orted to the client At this time, the pointer again 
appears to freeze. However, if the reported event 
causes the pointer grab to be released, the pointer does 
not freeze. SyncPointer has no effect if the pointer is 
not frozen by the client or if the pointer is not grabbed 
by the client. 

If the pointer is actively grabbed by the client and is 
frozen as the result of an event having been sent to the 
client (either from the activation of a XGrabButton or 
from a previous XAllowEvents with mode Sync- 
Pointer but not from a XGrabPointer), the pointer 
grab is released and that event is completely repro- 
cessed. This time, however, the function ignores any 
passive grabs at or above (towards the root of) the 
grab_window of the grab just released. The request 
has no effect if the pointer is not grabbed by the client 
or if the pointer is not frozen as the result of an event. 

If the keyboard is frozen by the client, keyboard event 
processing continues as usual. If the keyboard is 
frozen twice by the client on behalf of two separate 
grabs, AsyncKeyboard thaws for both. AsyncKfey- 
board has no effect if the keyboard is not frozen by 
the client, but the keyboard need not be grabbed by 
the client 

SyncKeyboard If the keyboard is frozen and actively grabbed by the 
dient, keyboard event processing continues as usual 



Replay- 
Pointer 
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until the next KeyPress or KeyRelease event is 
reported to the client. At this time, the keyboard again 
appears to freeze. However, if the reported event 
causes the keyboard grab to be released, the keyboard 
does not freeze. SyncKeyboard has no effect if the 
keyboard is not frozen by the client or if the keyboard 
is not grabbed by the client 

ReplayKtey- If the keyboard is actively grabbed by the client and is 
board frozen as the result of an event having been sent to the 

client (either from the activation of a XGrabKjey or from 
a previous XAllowEvents with mode SyncKeyboard 
but not from a XGrabKeyboard), the keyboard grab is 
released and that event is completely reprocessed. This 
time, however, the function ignores any passive grabs 
at or above (towards the root of) the grab_window of 
the grab just released. The request has no effect if the 
keyboard is not grabbed by the client or if the key- 
board is not frozen as the result of an event. 

SyncBoth If both pointer and keyboard are frozen by the client, 

event processing for both devices continues as usual 
until the next ButtonPress, ButtonRelease, 
KeyPress, or KeyRelease event is reported to the 
client for a grabbed device (button event for the 
pointer, key event for the keyboard), at which time the 
devices again appear to freeze. However, if the 
reported event causes the grab to be released, then the 
devices do not freeze (but if the other device is still 
grabbed, then a subsequent event for it will still cause 
both devices to freeze). SyncBoth has no effect unless 
both pointer and keyboard are frozen by the dient. If 
the pointer or keyboard is frozen twice by the dient on 
behalf of two separate grabs, SyncBoth thaws for both 
(but a subsequent freeze for SyncBoth will only freeze 
each device once). 

AsyncBoth If the pointer and the keyboard are frozen by the 

dient, event processing for both devices continues as 
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usual. If a device is frozen twice by the client on 
behalf of two separate grabs, AsyncBoth thaws for 
both. AsyncBoth has no effect unless both pointer and 
keyboard are frozen by the client. 

AsyncPointer, SyncPointer, and ReplayPointer have no effect on the pro- 
cessing of keyboard events. AsyncKeyboard, SyncKeyboard, and Replaylfey- 
board have no effect on the processing of pointer events. It is possible for both 
a pointer grab and a keyboard grab (by the same or different clients) to be 
active simultaneously. If a device is frozen on behalf of either grab, no event 
processing is performed for the device. It is possible for a single device to be 
frozen because of both grabs. In this case, the freeze must be released on behalf 
of both grabs before events can again be processed. 

XAllowEvents can generate a BadValue error. 
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Xlib provides functions that you can use to grab and ungrab the server. These 
functions can be used to control processing of output on other connections by 
the window system server. While the server is grabbed, no processing of 
requests or close downs on any other connection will occur. A client dosing its 
connection automatically ungrabs the server. 

Although grabbing the server is highly discouraged, it is sometimes necessary. 
To grab the server, use XGrabServer. 



XGrabServttr (display) 
Display ^display; 

display Specifies the connection to the XWIN server. 

The XGrabServer function disables processing of requests and close downs on 
all other connections than the one this request arrived on. You should not grab 
the XwiN server any more than is absolutely necessary. 

To ungrab the server, use XUngrabServer. 

XOhgrabServor ( display) 
Display ^display; 

display Specifies the connection to the XwiN server. 

The XCJngrabServer function restarts processing of requests and close downs on 
other connections. You should avoid grabbing the XwiN server as much as pos- 
sible. 
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This section discusses how to: 

■ Control the input focus 

■ Control the pointer 

■ Kill clients 

Controlling Input Focus 

Xlib provides functions that you can use to move the pointer position as well as 
to set and get the input focus. 

To move the pointer to an arbitrary point on the screen, use XWarpPointer. 

yjlilarpBointBr (display, srcjo, destjo, srcjc, srcjf, srcjMth, srcjieight, destjc, 
destjf) 
Display ^display; 
Window srcjp, destjo; 
int srcjc, srcjf; 

unsigned int srcjoidth, srcjieight; 
int destjc, destjf; 

display Specifies the connection to the XwiN server. 

srcjv Specifies the source window or None. 

destjv Specifies the destination window or None. 

srcjc 
srcjf 
srcjmdth 

srcjieight Specify a rectangle in the source window. 
destjc 

destjf Specify the x and y coordinates within the destination window. 

If dest_w is None, XWarpPointer moves the pointer by the offsets (dest_x, 
dest__y) relative to the current position of the pointer. If dest__w is a window, 
XWarpPointer moves the pointer to the offsets (dest_x, dest^y) relative to the 
origin of dest_w. However, if src_w is a window, the move only takes place if 
the specified rectangle src_w contains the pointer. 
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The src_x and src_y coordinates are relative to the origin of src_w. If src_height 
is zero, it is replaced with the current height of src_w minus src^y. If src__width 
is zero, it is replaced with the current width of src_w minus src_x. 

There is seldom any reason for calling this function. The pointer should nor- 
mally be left to the user. If you do use this function, however, it generates 
events just as if the user had instantaneously moved the pointer from one posi- 
tion to another. Note that you cannot use XWarpPointer to move the pointer 
outside the confine__to window of an active pointer grab. An attempt to do so 
will only move the pointer as far as the closest edge of the confine_to window. 

XWarpPointer can generate a BadWindow error. 

To set the input focus, use XSet Input Focus. 

XSetlr^tPocus {display, focus, revert Jo, time) 
Display "^display) 
Window )bc«s; 
int revert Jo; 
Time time; 

Specifies the connection to the XwiN server. 

Specifies the window, PointerRoot, or None. 

Specifies where the input focus reverts to if the window 
becomes not viewable. You can pass Revert ToParent, Revert- 
ToPointerRoot, or RevertToNone. 

time Specifies the time. You can pass either a timestamp or Current- 

Time. 

The XSet Input Focus function changes the input focus and the last-focus-change 
time. It has no effect if the specified time is earlier than the current last-focus- 
change time or is later than the current XwiN server time. Otherwise, the last- 
focus-change time is set to the specified time ( CurrentTime is replaced by the 
current XwiN server time). XSet Input Focus causes the XwiN server to generate 
Focusin and FocusOut events. 

Depending on the focus argument, the following occurs: 



display 

focus 

revertjo 
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■ If focus is None, all keyboard events are discarded until a new focus win- 
dow is set, and the revert_to argument is ignored. 

■ If focus is a window, it becomes the keyboard's focus window. If a gen- 
erated keyboard event would normally be reported to this window or one 
of its inferiors, the event is reported as usual. Otherwise, the event is 
reported relative to the focus window. 

■ If focus is Point erRoot, the focus window is dynamically taken to be the 
root window of whatever screen the pointer is on at each keyboard event. 
In this case, the revert_to argument is ignored. 

The specified focus window must be viewable at the time XSetlnputFocus is 
called, or a BadMatch error results. If the focus window later becomes not 
viewable, the XwiN server evaluates the revert__to argument to determine the 
new focus window as follows: 

■ If revert_to is Revert ToParent, the focus reverts to the parent (or the 
closest viewable ancestor), and the new revert_to value is taken to be 
RevertToNone. 

■ If revert_to is RevertToPointerRoot or RevertToNone, the focus reverts 
to PointerRoot or None, respectively. When the focus reverts, the XwiN 
server generates Focusin and FocusOut events, but the last-focus-change 
time is not affected. 

XSetlnputFocus can generate BadMatch, BadValue, and BadWindow errors. 

To obtain the current input focus, use TOetlnputFocus. 

XGetlr^tFocus {display, focus jetum, rmrtjojetwm) 
EHsplay *display; 
Window * focus jretum; 
int *revertJojetum; 

display Specifies the connection to the XwiN server. 

focus jreturn Returns the focus window, PointerRoot, or None. 

revertjojretum 

Returns the current focus state ( RevertToParent , RevertTo- 
PointerRoot, or RevertToNone). 
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The XGetlnputFocus function returns the focus window and the current focus 
state. 



Killing Clients 

Xlib provides functions that you can use to control the Ufetime of resources 
owned by a client or to cause the connection to a client to be destroyed. 

To change a client's dose-down mode, use XSetCloseDownMode. 

XSetCloseDotmMode {display, closejnode) 
I>isplay * display; 
int closejnode; 

display Specifies the connection to the XwiN server. 

closejnode Specifies the client close-down mode. You can pass Destroy- 
All, RetainPezmanent, or RetainTen^rary. 

The XSetCloseDownMode defines what will happen to the client's resources at 
connection close. A connection starts in DestroyAll mode. For information on 
what happens to the dienfs resources when the close_mode argument is 
RetainPerinanent or RetainTeinporary, see "X Server Connection Qose Opera- 
tions" in Chapter 2. 

XSetCloseDownMode can generate a BadValue error. 

To destroy a client, use XKillClient. 

XKillClient {display, resource) 
Display *disp1ay; 
XID resource; 

display Spedfies the connection to the XwiN server. 

resource Spedfies any resource assodated with the client that you want 

to destroy or AllTeniporary. 

The XKillClient function forces a dose-down of the client that created the 
resource if a valid resource is specified. If the client has already terminated in 
either RetainPerinanent or RetainTenporary mode, all of the client's resources 
are destroyed. If AllTeniporary is spedfied, the resources of all clients that 
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have ternriinated in RetainTeinporaury are destroyed (see "X Server Connection 
Close Operations" in Chapter 2). This permits implementation of window 
manager facilities that aid debugging. A client can set its close-down mode to 
RetainTen^rary. If the client then crashes, its windows would not be des- 
troyed. The programmer can then inspect the application's window tree and use 
the window manager to destroy the zombie windows. 

XKillClient can generate a BadValue error. 
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Xlib provides functions that you can use to change the keyboard control, obtain 
a list of the auto-repeat keys, turn keyboard auto-repeat on or off, ring the bell, 
set or obtain the pointer button or keyboard mapping, and obtain a bit vector 
for the keyboard. 

This section discusses the user-preference options of bell, key click, pointer 
behavior, and so on. The default values for many of these functions are deter- 
mined by command line arguments to the XwiN server and, on UNIX-based sys- 
tems, are typically set in the /etc/ttys file. 

Not all implementations will actually be able to control all of these parameters. 

The XChangeKeyboardControl function changes control of a keyboard and 
operates on a XKeyboardControl structure: 

/* Mask bits for ChangeKeyboardControl */ 



#define 


KBReyClickPercent 


(1L«0) 


#define 


KBBellPercent 


(1L«1) 


#define 


KBBellPitch 


(1L«2) 


#define 


KBBellDuration 


(1L«3) 


#define 


KBLed 


(1L«4) 


#define 


KBLedMode 


(1L«5) 


#define 


KBKey 


(1L«6) 


#define 


KBAutoRepeat:Mode 


(1L«7) 


/* Values 


*/ 




t^pedef struct { 





int key_clickjperoent; 
int bell_peroent; 
int belljpitch; 
int belljduratlon; 
int led; 

int ledjnods; /* LedModsOn, LedModeOff V 



int 
int 



key; 

autqjDepeat^mode; 



/* AutoRepeatModeO£f , AutoBepeatModsOn, 
AutoBepeatModeDefault */ 



} XKeyboardControl; 
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The key_click_percent member sets the volume for key clicks between 0 (off) 
and 100 Qoud) inclusive, if possible. A setting of -1 restores the default. Other 
negative values generate a BadValue error. 

The bellj>ercent sets the base volume for the bell between 0 (off) and 100 (loud) 
inclusive, if possible. A setting of -1 restores the default. Other negative values 
generate a BadValue error. The bell_pitch member sets the pitch (specified in 
Hz) of the bell, if possible. A setting of -1 restores the default. Other negative 
values generate a BadValue error. The bell_duration member sets the duration 
of the bell specified in milliseconds, if possible. A setting of -1 restores the 
default. Other negative values generate a BadValue error. 

If both the led^mode and led members are specified, the state of that LED is 
changed, if possible. The led_mode member can be set to LedModeOn or Led- 
ModeOf f . If only led_mode is specified, the state of all LEDs are changed, if 
possible. At most 32 LEDs numbered from one are supported. No standard 
interpretation of LEDs is defined. If led is specified without led mode, a Bad- 
Match error results. 

If both the auto_repeat_mode and key members are specified, the 
auto__repeat_mode of that key is changed (according to AutoRepeatMcxleOn, 
AutoRepeatMDdeOff , or AutoRepeatModeDefault), if possible. If only 
auto_repeat_mode is specified, the global auto repeat mode for the entire key- 
board is changed, if possible, and does not affect the per key settings. If a key 
is specified without an auto_repeat_mode, a BadMatch error results. Each key 
has an individual mode of whether or not it should auto-repeat and a default 
setting for the mode. In addition, there is a global mode of whether auto-repeat 
should be enabled or not and a default setting for that mode. When global 
mode is AutoRepeatModeOn, keys should obey their individual auto-repeat 
modes. When global mode is AutoRepeat:McxieO££, no keys should auto-repeat. 
An auto-repeating key generates alternating KeyPress and KfeyRelease events. 
When a key is used as a modifier, it is desirable for the key not to auto-repeat, 
regardless of its auto-repeat setting. 

A bell generator connected with the console but not directly on a keyboard is 
treated as if it were part of the keyboard. The order in which controls are 
verified and altered is server-dependent. If an error is generated, a subset of the 
controls may have been altered. 
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XCha]:igieICe:^x>ardControl {disjjiay, value jnask, vdues) 
Display ^display; 
unsigned long value jnask; 
XKeyboardControl ^values; 

display Specifies the connection to the XwiN server. 

value jnask Specifies one value for each bit set to 1 in the mask. 

values Specifies which controls to change. This mask is the bitwise 

inclusive OR of the valid control mask bits. 

The XChangeKeyboardControl function controls the keyboard characteristics 
defined by the XKeyboardControl structure. The value_mask argument 
specifies which values are to be changed. 

XChangeKeyboardControl can generate BadMatch and BadValue errors. 

To obtain the current control values for the keyboard, use XGetKeyboardCon- 
trol. 

XGetKeyboardControl {display, valuesjretum) 
Display ^display; 
XKeyboardState *values_retum; 

display Specifies the connection to the XwiN server. 

valuesjretum Returns the current keyboard controls in the specified XKey- 
boardState structure. 

The XGetKeyboardControl function returns the current control values for the 
keyboard to the XKeyboardState structure. 

typedef struct { 

int keyjclicJcjperoent; 
int bell_peroent; 

unsigned int belljpitch, belljduratlon; 
unsigned long ledjnask; 
int global_auto_repeat; 
char auto_r^peats [32] ; 
} XKeyboardState; 

For the LEDs, the least-significant bit of led_mask corresponds to LED one, and 
each bit set to 1 in led_mask indicates an LED that is lit. The 
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global_auto_repeat member can be set to AutoRepeatModeOn or AutoRepeat- 
ModeOf f . The auto repeats member is a bit vector. Each bit set to 1 indicates 
that auto-repeat is enabled for the corresponding key. The vector is represented 
as 32 bytes. Byte N (from 0) contains the bits for keys 8N to 8N + 7 with the 
least-significant bit in the byte representing key 8N. 

To turn on keyboard auto-repeat, use XAutoRepeatOn. 

XAutoRepeatOn ( display) 
Display ^display; 

display Specifies the connection to the XWIN server. 

The XAutoRepeatOn function turns on auto-repeat for the keyboard on the 
specified display. 

To turn off keyboard auto-repeat, use XAutoRepeatOf f . 

XAutoUBpeatOff (display) 
Display * display; 

display Specifies the connection to the XwiN server. 

The XAutoRepeatOf f function turns off auto-repeat for the keyboard on the 
specified display. 

To ring the bell, use XBell. 

XBell (display, percent) 
Display ^display; 
int percent; 

display Specifies the connection to the XwiN server. 

percent Specifies the volume for the bell, which can range from -100 to 

100 inclusive. 

The XBell function rings the bell on the keyboard on the specified display, if 
possible. The specified volume is relative to the base volume for the keyboard. 
If the value for the percent argument is not in the range -100 to 100 inclusive, a 
BadValue error results. The volume at which the bell rings when the percent 
argument is nonnegative is: 
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base - [(base * percent) / 100] + percent 

The volume at which the bell rings when the percent argument is negative is: 
base + [(base * percent) / 100] 

To change the base volume of the bell, use XChangeKeyboardControl. 
XBell can generate a BadValue error. 

To obtain a bit vector that describes the state of the keyboard, use XQueryKey- 
inap. 

lXQijiBr}f!^ymap{displa}f, keysjretum) 
Display ^display; 
diar kgysjretuml32]; 

display Specifies the connection to the XwiN server. 

keysjetum Returns an array of bytes that identifies which keys are pressed 
down. Each bit represents one key of the keyboard. 

The ^KJueryKeyinap function returns a bit vector for the logical state of the key- 
board, where each bit set to 1 indicates that the corresponding key is currently 
pressed down. The vector is represented as 32 bytes. Byte N (from 0) contains 
the bits for keys 8N to 8N + 7 with the least-significant bit in the byte represent- 
ing key 8N. 

Note that the logical state of a device (as seen by client applications) may lag 
the physical state if device event processing is frozen. 

To set the mapping of the pointer buttons, use XSetPointerMapping. 

int XSetPointerMappixig(iis;:^2<zy/ mop, nmap) 
Display *display; 
unsigned diar mapQ; 
int nmap; 

display Specifies the connection to the XwiN server. 

map Specifies the mapping list. 
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nmap Specifies the number of items in the mapping list. 

The XSetPointerMapping function sets the mapping of the pointer. If it 
succeeds, the XWIN server generates a MappingNotif y event, and XSetPointer- 
Mapping returns MappingSuccess. Elements of the list are indexed starting 
from one. The length of the list must be the same as XGetPointerMapping 
would return, or a BadValue error results. The index is a core button number, 
and the element of the list defines the effective number. A zero element dis- 
ables a button, and elements are not restricted in value by the number of physi- 
cal buttons. However, no two elements can have the same nonzero value, or a 
BadValue error results. If any of the buttons to be altered are logically in the 
down state, XSetPointerMapping returns MappingBusy, and the mapping is 
not changed. 

XSetPointei^pping can generate a BadValue error. 

To get the pointer mapping, use XGetPointerMapping. 

int XGetPotnteiHa^ing (iltsplay, mapjetum, nmap) 
Display ^display) 
tinsigned char mapjretumW; 
int fimup) 

display Specifies the connection to the XwiN server. 

mapjetum Returns the mapping list. 

nmap Specifies the number of items in the mapping list 

The XGetPointerMapping function returns the current mapping of the pointer. 
Elements of the list are indexed starting from one. XGetPointerMapping 
returns the number of physical buttons actually on the pointer. The nominal 
mapping for a pointer is the identity mapping: map[i]=i. The nmap argument 
specifies the length of the array where the pointer mapping is returned, and 
only the first nnup elements are returned in map_retum. 

To control the pointer's interactive feel, use XChangePointerControl. 
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XChangaPointerControl {disphnf, dojuxel, dojhreshold, acceljiumerator, 
accdjienominator, ihreshold) 
Display *display; 
Bool dojiccel, dojhreshold; 
int acceljtumerator, accdjtenominator; 
int threshold; 

display Specifies the connection to the XwiN server. 

dojuxel Specifies a Boolean value that controls whether the values for 

the accel_numerator or accel_denominator are used. 

dojhreshold Specifies a Boolean value that controls whether the value for the 
threshold is used. 

acceljtumerator 

Specifies the numerator for the acceleration multiplier. 

acceldenotninator 

Specifies the denominator for the acceleration multiplier. 

threshold Specifies the acceleration threshold. 

The XChangePointerControl function defines how the pointing device moves. 
The acceleration, expressed as a fraction, is a multiplier for movement. For 
example, specifying 3/1 means the pointer moves three times as fast as normal. 
The fraction may be rounded arbitrarily by the XwiN server. Acceleration only 
takes effect if the pointer moves more than threshold pixels at once and only 
applies to the amount beyond the value in the threshold argument. Setting a 
value to -1 restores the default. The values of the do accel and do_threshold 
arguments must be True for the pointer values to be set, or the parameters are 
unchanged. Negative values (other than -1) generate a BadValue error, as does 
a zero value for the accel_denominator argument. 

XChangePointerControl can generate a BadValue error. 

To get the current pointer parameters, use XGetPointerControl. 

XGetPointexControl ( display, accdjtumeratorjretum, accel^denomimtorjetum, 
ihresholdjetum) 
Display ^display; 

int *acceljiumeratorjretum, *accd_denomimtorjvUim; 
int *threshoidjetum; 
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display Specifies the connection to the XWDsr server. 

acceljtutneratorjretum 

Returns the numerator for the acceleration multiplier. 

acceljlenamimtorjretum 

Returns the denominator for the acceleration multiplier. 

thresholdjreturn 

Returns the acceleration threshold. 

The XGetPointerControl function returns the pointer's current acceleration 
multiplier and acceleration threshold. 



Window Manager Functions 



7-37 



Keyboard Encoding 



Most applications will find the simple interface XLookvqpString, which performs 
simple translation of a key event to an ASCII string, most useful. Keyboard- 
related utilities are discussed in Chapter 10. The following section explains how 
to completely control the bindings of symbols to keys and modifiers. 

A KeyCode represents a physical (or logical) key. KeyCodes lie in the inclusive 
range [8,255]. A KeyCode value carries no intrinsic information, although server 
implementors may attempt to encode geometiy (for example, matrix) informa- 
tion in some fashion so that it can be interpreted in a server-dependent fashion. 
The mapping between keys and KeyCodes cannot be changed. 

A KeySym is an encoding of a symbol on the cap of a key. The set of defined 
KeySyms include the ISO Latin character sets (1-4), Katakana, Arabic, Cyrillic, 
Greek, Technical, Special, Publishing, APL, Hebrew, and a special miscellany of 
keys found on keyboards (Return, Help, Tab, and so on). To the extent possible, 
these sets are derived from international standards. In areas where no standards 
exist, some of these sets are derived from Digital Equipment Corporation stan- 
dards. The list of defined symbols can be found in < Xll/keysymdef .h >. 
Unfortunately, some C preprocessors have limits on the number of defined sym- 
bols. If you must use KeySyms not in the Latin 1-4, Greek, and miscellaneous 
classes, you may have to define a symbol for those sets. Most applications usu- 
ally only include < Xll/keysyra.h >, which defines symbols for ISO Latin 1-4, 
Greek, and miscellaneous. 

A list of Ke)^yms is associated with each KeyCode. The length of the list can 
vary with each KejK^ode. The list is intended to convey the set of symbols on 
the corresponding key. By convention, if the list contains a single KeyS)^! and if 
that KeySym is alphabetic and case distinction is relevant for it, then it should 
be treated as equivalent to a two-element list of the lowercase and uppercase 
KeySyms. For example, if the list contains the single KeySym for uppercase A, 
the client should treat it as if it were a pair with lowercase a as the first KeySym 
and uppercase A as the second KeySym. 

For any KeyCode, the first KeySym in the list should be chosen as the interpre- 
tation of a KeyPress when no modifier keys are down. The second KeySym in 
the list normally should be chosen when the Shift modifier is on or when the 
Lock modifier is on and Lock is interpreted as ShiftLock. When the Lock 
modifier is on and is interpreted as (fapsLock, it is suggested that the Shift 
modifier first be applied to choose a KeySym. However, if that KejrSym is 
lowercase alphabetic, the corresponding uppercase KeySym should be used 
instead. Other interpretations of CapsLock are possible; for example, it may be 
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viewed as equivalent to ShiftLock, but only applying when the first KeySym is 
lowercase alphabetic and the second KeySym is the corresponding uppercase 
alphabetic. No interpretation of KeySynns beyond the first two in a list is sug- 
gested here. No spatial geometry of the symbols on the key is defined by their 
order in the KeySym list, although a geometry might be defined on a vendor- 
specific basis. The XWIN server does not use the mapping between KeyCodes 
and Ke)65mis. Rather, it stores it merely for reading and writing by clients. 

To obtain the legal KeyCodes for a display, use XDisplayKeycodes. 

XDispla^yoodas (itsp2ay, minjseycodesjetum, nuxjoeycodesjeturn) 
Display ^display; 

int *minJxycodesjetum, maxjoeycodesjretum; 

display Specifies the connection to the XwiN server. 

minjoeycodesjetum 

Returns the minimum number of KeyCodes. 

maxjxycodesjetum 

Returns the maximum number of KeyCodes. 

The XDisplayKeycodes function returns the min-keycodes and max-keycodes 
supported by the specified display. The minimum number of KeyCodes 
returned is never less than 8, and the maximum number of KeyCodes returned 
is never greater than 255. Not all KeyCodes in this range are required to have 
corresponding keys. 

To obtain the symbols for the specified KeyCodes, use XGetK^yboardMapping. 

IteyS^ *ySji9^J^'^boardtfiSLy^ 

ksysyntsjperjoeycodejeturn ) 
Display ^display; 
KeyCode first Jceycode; 
int ktycodejxmnt; 
int "^hBysymsjmrJxycodejetwrn*, 

display Specifies the connection to the XwiN server. 
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firstjceycode Specifies the first KeyCode that is to be returned. 

keycode_count Specifies the number of KeyCodes that are to be returned. 

keysymsj>erJceycode_return 

Returns the number of KeySyms per KeyCode. 

The TOetKeyboardMapping function returns the symbols for the specified 
number of Ke)<;odes starting with first_keycode. The value specified in 
first keycode must be greater than or equal to min_keycode as returned by 
XDisplayKeycodes, or a BadValue error results. In addition, the following 
expression must be less than or equal to max_keycode as returned by 
XDisplayKeycodes : 

f irstjceyoodtt keycsodejcount - 1 

If this is not the case, a BadValue error results. The number of elements in the 
Ke563mis list is: 

]ceycodajcx>unt * keysyniB^per Jceyoodejretuzn 

KeySym ntunber N, counting from zero, for KeyCode K has the following index 
in the list, counting from zero: 

(K - f irstjoode) * keysymajperjcxxiejcetuxn + N 

The XwiN server arbitrarily chooses the keysyms_per_keycode_retum value to 
be large enough to report all requested symbols. A special KeySym value of 
NoSyinbol is used to fill in imused elements for individual KeyCodes. To free 
the storage returned by XGetKeyboardMapping, use XFree. 

XGetKeyboardMapping can generate a BadValue error. 

To change the keyboard mapping, use XChangeKeyboardMapping. 

XChangeKe^>oardMapping (<2isplay, first Jxycode, keysymsjperjotycode, keysyms, numjsodes) 
Display * display, 
int firstjceycode; 
int keysymsjxrjxycode; 
KeySym *keysyms; 
int mmjcodes) 
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display Specifies the connection to the XwiN server. 

first Jceycode Specifies the first KeyCode that is to be changed. 

keysymsj)erJceycode 

Specifies the number of KeyS)m[is per KeyCode. 

keysyms Specifies a pointer to an array of KeySyn\s. 

numj:odes Specifies the number of KeyCodes that are to be changed. 

The XChangeKeyboardMapping function defines the symbols for the specified 
number of KeyCodes starting with first Jceycode. The symbols for KeyCodes 
outside this range remain unchanged. The number of elements in keysyms must 
be: 

num^oodes * keysyros^perjceycode 

The specified first keycode must be greater than or equal to min keycode 
returned by XDisplayKeycodes, or a BadValue error results. In addition, the 
following expression must be less than or equal to max keycode as returned by 
XDisplayKeycodes, or a BadValue error results: 

f irstjceycode -I- numjcsodes - 1 

KeySym number N, counting from zero, for KeyCode K has the following index 
in keysyms, counting from zero: 

(K - f irstjceycode) * keysyms^perjceyoode + N 

The specified keysyms_per_keycode can be chosen arbitrarily by the client to be 
large enough to hold all desired symbols. A special KeySym value of NoSyrabol 
should be used to fill in unused elements for individual KeyCodes. It is legal for 
NoSyrabol to appear in nontrailing positions of the effective list for a KeyCode. 
XChangeKeyboardMapping generates a MappingNotify event. 

There is no requirement that the XwiN server interpret this mapping. It is 
merely stored for reading and writing by clients. 

XChangeKeyboardMapping can generate BadAlloc and BadValue errors. 

The next four functions make use of the XModif ierKeyraap data structure, 
which contains: 
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typedef struct { 

int naxjceypexmod; /* This server's max nunber of keys per modifier */ 

Ke^ode ^modifiermap; /* An 8 by maxjceypermod array of the modifiers */ 
} XModifieriCeymap; 

To create an XModif ierKeymap structure, use XNewModif iermap. 

XModifiejdCeymap *XNei«fodifiermap(maxj£ysjierjfi(Ml) 

int maxjxysjperjnod; 

max Joeys jperjnod 

Specifies the number of KeyCode entries preallocated to the 
modifiers in the map. 

The XNewModif iernap function returns a pointer to XModif IerKeymap structure 
for later use. 

To add a new entry to an XModif ierKeymap structure, use XInsertModif ier- 
mapEntry. 

XMDdif ierKeymap *XInsertMcxiifiermaFEntry ( moima^, Xseycois^m^, moi^i^ 
XModiflerKeymap *modmap; 
KeyCode keycodejentry; 
int modifier; 

modmap Specifies a pointer to the XModif ierKeymap structure. 

keycodejntry Specifies the KeyCode. 
modifier Specifies the modifier. 

The XinsertModif iermapEntry function adds the specified KeyCode to the set 
that controls the specified modifier and returns the resulting XModif ierKeymap 
structure (expanded as needed). 

To delete an entry from an XModif ierKeymap structure, use XDeleteModif ier- 
mapEntry. 

XModif ieidCeymi^ ^XDeleteModifiermapEntry (moimap, keycodejntry, modifier) 
XModiflerKeymap *modmap; 
KeyCode keycodejntry; 
int modifier; 
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modmap Specifies a pointer to the XModif ierKeyraap structure. 

keycode_mtry Specifies the KeyCode. 
modifier Specifies the modifier. 

The XDeleteModif ierniapEntry function deletes the specified KeyCode from 
the set that controls the specified modifier and returns a pointer to the resulting 
XMcxii£ierKeyinap structure. 

To destroy an XModifierK^ynap structure, use XFreeModi£iezinap. 

XFraeModif iermap {modmap) 

XModifierKeymap *modmap; 

modmap Specifies a pointer to the XMcxiifierK^ynap structure. 

The XFreeModlflennap function frees the specified XModlflerKeymap structure. 
To set the KeyCodes to be used as modifiers, use XSetModifierMapping. 

int XStttModifittjAi8g;^in9 ( iltsp2ay, mofimap) 
EHsplay ^display; 
XModifierKeymap *modmap; 

display Specifies the connection to the XwiN server. 

modmap Specifies a pointer to the XModif ierKeynap structure. 

The XSetModifierMapping function specifies the KeyCodes of the keys (if any) 
that are to be used as modifiers. If it succeeds, the XwiN server generates a Map- 
pingNotify event, and XSetMcxiifierMapping returns MappingSuccess. X 
permits at most eight modifier keys. If more than eight are specified in the XMd- 
difierKeyniap structure, a BadLength error results. 

The modifiermap member of the XModif ierKeyitap structure contains eight sets 
of max__keypermod KeyCodes, one for each modifier in the order Shift, Lock, 
Control, Modi, Mod2, Mod3, Mod4, and Mod5. Only nonzero KeyCodes have 
meaning in each set, and zero KeyCodes are ignored. In addition, all of the 
nonzero KeyCodes must be in the range specified by min_keycode and 
max^keycode in the Display structure, or a BadValue error results. No Key- 
Code may appear twice in the entire map, or a BadValue error results. 
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An XwiN server can impose restrictions on how nKxlifiers can be changed, for 
example, if certain keys do not generate up transitions in hardware, if auto- 
repeat cannot be disabled on certain keys, or if multiple modifier keys are not 
supported. If some such restriction is violated, the status reply is Mapping- 
Failed, and none of the modifiers are changed. If the new KeyCodes specified 
for a modifier differ from those currently defined and any (current or new) keys 
for that modifier are in the logically down state, XSetModif ierMapping returns 
MappingBusy, and none of the modifiers is changed. 

XSetModif ierMapping can generate BadAlloc and BadValue errors. 

To obtain the Ke)rCodes used as modifiers, use XGetModif ierMapping. 

XModifiezKeymap *XGetMcxiifiezKaFping(<{isp/ffy) 

Display ^display; 



display Specifies the connection to the XwiN server. 

The XGetMcxiif ierMapping function returns a pointer to a newly created XMo- 
dif ierKeyniap structure that contains the keys being used as modifiers. The 
structure should be freed after use by calling XFreeMcxiif iermap. If only zero 
values appear in the set for any modifier, that modifier is disabled. 
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Xlib provides functions that you can use to set, force, activate, or reset the 
screen saver and to obtain the current screen saver values. 

To set the screen saver, use XSetScreenSaver. 

YSmtSGJntmnSwwc {display, timeout, interval, jfreferjiianking, attow_pcposures) 
Display "^display; 
int timeout, interval; 
int jnreferjflankmg; 
int allowjscposures; 

display Specifies the connection to the XwiN server. 

timeout Specifies the timeout, in seconds, until the screen saver turns on. 

interval Specifies the interval between screen saver alterations. 

prefer J)hnking 

Specifies how to enable screen blanking. You can pass DontPre- 
ferBlanking, PreferBlanking, or DefaultBlanking. 

allow jxposures 

Specifies the screen save control values. You can pass DontAl- 
lowE2q)osures, AllowE:qposures, or DefaultExposures. 

Timeout and interval are specified in seconds. A timeout of 0 disables the screen 
saver, and a timeout of -1 restores the default. Other negative values generate 
a BadValue error. If the timeout value is nonzero, XSetScreenSaver enables 
the screen saver. An interval of 0 disables the random-pattern motion. If no 
input from devices (keyboard, mouse, and so on) is generated for the specified 
number of timeout seconds once the screen saver is enabled, the screen saver is 
activated. 

For each screen, if blanking is preferred and the hardware supports video blank- 
ing, the screen simply goes blank. Otherwise, if either exposures are allowed or 
the screen can be regenerated without sending E^spose events to clients, the 
screen is tiled with the root window background tile randomly re-origined each 
interval minutes. Otherwise, the screens' state do not change, and the screen 
saver is not activated. The screen saver is deactivated, and all screen states are 
restored at the next keyboard or pointer input or at the next call to 
XForceScreenSaver with mode ScreenSaverReset. 
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If the server-dependent screen saver method supports periodic change, the inter- 
val argument serves as a hint about how long the change period should be, and 
zero hints that no periodic change should be made. Examples of ways to 
change the screen include scrambling the colormap periodically, moving an icon 
image around the screen periodically, or tiling the screen with the root window 
background tile, randomly re-origined periodically. 

XSetScreenSaver can generate a BadValue error. 

To force the screen saver on or off, use XForceScreenSaver. 

XForoeScraanSavsr {display, mode) 
Display ^display; 
intmode; 

display Specifies the connection to the XwiN server. 

mode Specifies the mode that is to be applied. You can pass Screen- 

SaverActive or ScreenSaverReset. 

If the specified mode is ScreenSaverActive and the screen saver currently is 
deactivated, XForceScreenSaver activates the screen saver even if the screen 
saver had been disabled with a timeout of zero. If the specified mode is 
ScreenSaverReset and the screen saver currently is enabled, XForceScreen- 
Saver deactivates the screen saver if it was activated, and the activation timer is 
reset to its initial state (as if device input had been received). 

XForceScreenSaver can generate a BadValue error. 

To activate the screen saver, use XActivateScreenSaver. 

XActivataScreenSaver {display) 
Display ^display; 

display Specifies the connection to the XwiN server. 

To reset the screen saver, use XReset Screensaver. 

XRssetScroenSavBr {display) 
Display ^display; 
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display 



Specifies the connection to the XwiN server. 



To get the current screen saver values, use XGetScreenSaver. 

XGetScreenSaver (<^isp2ay, timeout jretum, interval jetum, jfreferj}lanking_retum, 



edUmjocposuresjretum ) 
Display ^display; 

int * timeout jretum, * interval jetum; 
int *preferj>lanking jretum; 
int *allow_exposuresj^tum; 



timeout jetum 

Returns the timeout, in minutes, until the screen saver turns on. 

intervaljetum 

Returns the interval between screen saver invocations. 

prefer J)lankingjeiurn 

Returns the current screen blanking preference ( DontPref er- 
Blanking , PreferBlanking, or DefaultBlanking). 

allow ^exposures jetum 

Returns the current screen save control value ( DontAllowExpo- 
sures , AllowExposures, or DefaultExposures). 



display 



Specifies the connection to the XwiN server. 
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This section discusses how to: 

■ Add, get, or remove hosts from the access control list 

■ Change, enable, or disable access 

X does not provide any protection on a per-window basis. If you find out the 
resource ID of a resource, you can manipulate it. To provide some minimal 
level of protection, however, connections are permitted only from machines you 
trust. This is adequate on single-user workstations but obviously breaks down 
on timesharing machines. Although provisions exist in the X protocol for 
proper connection authentication, the lack of a standard authentication server 
leaves host-level access control as the only common mechanism. 

The initial set of hosts allowed to open connections typically consists of: 

■ The host the window system is running on. 

■ On UNIX-based systems, each host listed in the /etc/X?. hosts file. The 
? indicates the number of the display. 

This file should consist of host names separated by newlines. 

If a host is not in the access control list when the access control mechanism is 
enabled and if the host attempts to establish a connection, the server refuses the 
connection. To change the access list, the client must reside on the same host as 
the server and/or must have been granted permission in the initial authoriza- 
tion at connection setup. 

Servers also can implement other access control policies in addition to or in 
place of this host access facility. For further information about other access con- 
trol implementations, see "X Window System Protocol." 
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Adding, Getting, or Removing Hosts 



Xlib provides functions that you can use to add, get, or remove hosts from the 
access control list. All the host access control functions use the XHostAddress 
structure, which contains: 

typadef struct { 



> XHostikkLress; 

The family member specifies which protocol address family to use. The length 
member specifies the length of the address in bytes. The address member 
specifies a pointer to the address. For TCP/IP, the address should be in net- 
work byte order. 

To add a single host, use XAddHost. 

XAddHost {display, host) 
Display ^display; 
XHostAddress *host; 

display Specifies the connection to the XwiN server. 

host Specifies the host that is to be added. 

The XAddHost function adds the specified host to the access control list for that 
display. The server must be on the same host as the client issuing the com- 
mand, or a BadAccess error results. 

XAddHost can generate BadAccess and BadValue errors. 

To add multiple hosts at one time, use XAddHost s. 

XAddHoflts {display, hosts, numjiosts) 
Display *display; 
XHostAddress *hosts; 
int numjiosts; 



int family; 
int length; 
char *addre88; 



/* for example Familylntemet */ 

/* lengtih of address, in bytes V 

/* pointer to Where to find the address */ 
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display 
hosts 



Specifies the connection to the XwiN server. 
Specifies each host that is to be added. 
Specifies the number of hosts. 



num hosts 



The XAddHosts function adds each specified host to the access control hst for 
that display. The server must be on the same host as the client issuing the com- 
mand, or a BadAccess error results. 

XAddHosts can generate BadAccess and BadValue errors. 

To obtain a host list, use XListHosts. 

XHostAddress ^XListHosts (display, nhostsjetum, state jetum) 



rihostsjretum Returns the number of hosts currently in the access control list. 
state jetum Returns the state of the access control. 

The XListHosts function returns the current access control list as well as 
whether the use of the list at connection setup was enabled or disabled. 
XListHosts allows a program to find out what machines can make connections. 
It also returns a pointer to a list of host structures that were allocated by the 
function. When no longer needed, this memory should be freed by calling 
XFree. 

To remove a single host, use XRenioveHost. 

XReokoveHost {display, host) 
Display ^display; 
XHostAddress *host; 

display Specifies the connection to the XwiN server. 

host Specifies the host that is to be removed. 



Display * display; 
int *nhosts_retum; 
Bool *statejetum) 



display 



Specifies the connection to the XwiN server. 
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The XRemoveHost function removes the spedfied host from the access control 
list for that display. The server must be on the same host as the client process, 
or a BadAccess error results. If you remove your machine from the access list, 
you can no longer connect to that server, and this operation cannot be reversed 
unless you reset the server. 

XRemoveHost can generate BadAccess and BadValue errors. 

To remove multiple hosts at one time, use XRemoveHost s. 

XRemoveHosts {display, hosts, numjiosts) 
Display * display; 
XHostAddress *hosis; 
int numjiosts; 

display Specifies the connection to the XwiN server. 

hosts Specifies each host that is to be removed. 

numjiosts Specifies the number of hosts. 

The XRemDveHosts function removes each specified host from the access control 
hst for that display. The XwiN server must be on the same host as the client pro- 
cess, or a BadAccess error results. If you remove your machine from the access 
list, you can no longer connect to that server, and this operation cannot be 
reversed unless you reset the server. 

XRemoveHosts can generate BadAccess and BadValue errors. 

Changing, Enabling, or Disabling Access Control 

Xlib provides functions that you can use to enable, disable, or change access 
control. 

For these functions to execute successfully, the client application must reside on 
the same host as the XwiN server and/or have been given permission in the ini- 
tial authorization at connection setup. 

To change access control, use XSetAccessControl. 
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XSetAcsoessControl {display, mode) 
Display ^display; 
int mode; 

display Specifies the connection to the XwiN server. 

mode Specifies the mode. You can pass EnableAccess or 

DlsableAccess. 

The XSetAccessControl function either enables or disables the use of the 
access control list at each connection setup. 

XSet:AccessControl can generate BadAccess and BadValue errors. 
To enable access control, use XEnableAccessControl. 

XEnableAocsesaControl (display) 
Display ^display; 

display Specifies the connection to the XwiN server. 

The XEnableAccessCk^ntrol function enables the use of the access control list at 
each connection setup. 

XEnableAcx^essControl can generate a BadAccess error. 

To disable access control, use XDisableAcoessControl. 

XDisableAcoessControl (display) 
Display ^display; 

display Specifies the connection to the XwiN server. 

The XDisableAccessControl function disables the use of the access control list 
at each connection setup. 

XDisableAccessControl can generate a BadAccess error. 
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Introduction 



A client application communicates with the XwiN server through the connection 
you establish with the XOpenDisplay function. A client application sends 
requests to the Xwnsr server over this connection. These requests are made by 
the Xlib functions that are called in the client application. Many Xlib functions 
cause the XwiN server to generate events, and ihe user's typing or moving the 
pointer can generate events asynchronously. The XwiN server returns events to 
the client on the same connection. 

This chapter begins with a discussion of the following topics associated with 
events: 

■ Event types 

■ Event structures 

■ Event mask 

■ Event processing 

It then discusses the Xlib functions you can use to: 

■ Select events 

■ Handle the output buffer and the event queue 

■ Select events from the event queue 

■ Send and get events 

■ Handle error events 



NOTE 



Some toolkits use their own event-handling functions and do not allow you to 
interchange these event-handling functions with those in Xlib. For further 
information, see the documentation supplied with the toolkit. 



Most applications simply are event loops: they wait for an event, decide what to 
do with it, execute some amount of code that results in changes to the display, 
and then wait for the next event. 
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Event Types 



An event is data generated as)mchronously by the XwiN server as a result of 
some device activity or as side effects of a request sent by an Xlib function. 
Device-related events propagate from the source window to ancestor windows 
until some client application has selected that event type or until the event is 
explicitly discarded. The XwiN server generally sends an event to a client appli- 
cation only if the client has specifically asked to be informed of that event type, 
typically by setting the event-mask attribute of the window. The mask can also 
be set when you create a window or by changing the window's event-mask. 
You can also mask out events that would propagate to ancestor windows by 
manipulating the do-not-propagate mask of the window's attributes. However, 
MappingNotify events are always sent to all clients. 

An event type describes a specific event generated by the Xwnsr server. For each 
event type, a corresponding constant name is defined in < Xll/X.h >, which is 
used when referring to an event type. 

The following table lists the event category and its associated event type or 
types. The processing associated with these events is discussed in "Event Pro- 
cessing" in this chapter. 
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Event Category 


Event Type 


Keyboard events 




Pointer events 


ButifcohPrttflS RiiM'nnftnlftann lft>fciohlIotifv 


Window crossing events 


EatmtVtotity, LeaviM>ti£y 


InDiit focus events 

AXIfc^Ub WVdl»0 




TCevmaD state notification event 


*VB JfUia.^^ V w X JL 


Exposure events 


Expose, GraphicaBjqpose/ MbExpoae 


Structure control events 


CirculateRaquest, Conf igureiRBquest, MapRBquest, 




BeBizeRecpiest 


Window state notification events 


ClrcuUt^tify, Conf igureNbtify, Cxeat^otify, 




DestroyNotify, GravityNotify, MapNotify/ MappingNo- 




tify, ReparentMbtify, UnmapNotify/ VisibilityNotif y 


Colormap state notification event 


ColoxniiqpMot ity 


Client communication events 


ClientMasaage, PropertyNotify, SelectionClear, 




Selectio]iN6tify, SelectionRaquest 
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For each event type, a corresponding structure is declared in < Xll/Xlib.h >. 
All the event structures have the following common members: 

typedef struct { 
int type; 

iinsigned long serial; /* # of last raqyest processed by server */ 
Bool sendjsvent; /* true if this cane from a SendBvent request */ 

Display *display; /* Display the event was read from */ 

Window window; 
) XAnyEvent; 

The type member is set to the event type constant name that uniquely identifies 
it. For example, when the XwiN server reports a GraphicsExpose event to a 
client application, it sends an XGraphicsExposeEvent structure with the type 
member set to GraphicsExpose. The display member is set to a pointer to the 
display the event was read on. The send_event member is set to True if the 
event came from a SendEvent protocol request. The serial member is set from 
the serial number reported in the protocol but expanded from the 16-bit least- 
significant bits to a full 32-bit value. The window member is set to the window 
that is most useful to toolkit dispatchers. 

The XwiN server can send events at any time in the input stream. Xlib stores 
any events received while waiting for a reply in an event queue for later use. 
Xlib also provides functions that allow you to check events in the event queue 
(see "Event Queue Management" in this chapter). 

In addition to the individual structures declared for each event type, the XEvent 
structure is a union of the individual structures declared for each event type. 
Depending on the type, you should access members of each event by using the 
XEvent union. 
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typadef union _XBv«nt { 

Int typo; /* must not be ohangod */ 

XAnyBvmt xany; 

XKByBvmt 3dcey; 

XButtonBvent sdautton; 

XMotionBvBnt jcnotion; 

XCrossing^Bvant xcrosBing; 

XFocusChangeBvant xfocus; 

XBxposttEEvent xoaqpose; 

XGraphicaEsqpoaeBvant xgraphicsexpose; 

XNoEsqpoaeEvent xnoexpose; 

XVisibilityBvwit xvisibility; 

XCreateWindoiiBvent xcreatttwindow; 

XDestroyWindowBvent xdestroywindow; 

XCftunapEvant xaanap; 

IQtopBvmiA xnap; 

XMapBeqpjestBvent xmaqprequest; 

XR^danuitSvant xreparent; 

XConfiguraBvent xoonfigure; 

XGravityBvient xgravity; 

XRBsizeRequestEvent xresizerequest; 

XConfiguraBequestBvent xoonfigurerequest; 

XCirculateBvent iccirculate; 

XCirculateRoquestBvent xciroulaterequest; 

XPropert^vent xproperty; 

2CSelectionClea]£viant xaelectionclear; 

XSelectionRaqueatBvent xselectionrequeat; 

XSelecti^uBvent xaelection; 

XColoxmapBv<ant xoolozma^; 

XClientMsssageEvent xclient; 

XMappin^^Bvent XBOi^ing; 

XErroriSvent xerror; 

XKeyma^Event sdceymap; 

long pad [24]; 
} XEvent; 



An XEvent structure's first entry always is the type member, which is set to the 
event type. The second member always is the serial number of the protocol 
request that generated the event. The third member always is send_event, 
which is a Bool that indicates if the event was sent by a different client. The 
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Event Structures 



fourth member always is a display, which is the display that the event was read 
from. Except for keymap events, the fifth member always is a window, which 
has been carefully selected to be useful to toolkit dispatdhers. To avoid break- 
ing toolkits, the order of these first five entries is not to change. Most events 
also contain a time member, which is the time at which an event occurred. In 
addition, a pointer to the generic event must be cast before it is used to access 
any other information in the structure. 



8-6 



Xwin GWS: Xlib - C Language Interface 



Event Masks 



Clients select event reporting of most events relative to a window. To do this, 
pass an event mask to an Xlib event-handling function that takes an event mask 
argument. The bits of the event mask are defined in < Xll/X. h >. Each bit in 
the event mask maps to an event mask name, which describes the event or 
events you want the XWIN server to return to a client application. 

Unless the client has specifically asked for them, most events are not reported to 
clients when they are generated. Unless the client suppresses them by setting 
graphics-exposures in the GC to False, GraphicsExpose and NoExpose are 
reported by default as a result of XCopyPlane and XCopyArea. Selection- 
Clear, Select lonRequest, Select ionNot if y, or ClientJMtessage cannot be 
masked. Selection related events are only sent to clients cooperating with selec- 
tions (see "Selections" in Chapter 4). When the keyboard or pointer mapping is 
changed, MappingNotif y is always sent to clients. 

The following table lists the event mask constants you can pass to the 
event_mask argument and the circumstances in which you would want to 
specify the event mask: 



Event Mask 



Qrcumstances 



NoEventMask 

KeyPressMask 

KeyReleaseMask 

ButtonPressMask 

ButtonReleaseMask 

EnterWindowMask 

LeaveWindov^sk 

PointerMotionMask 

PointerMo- 

tionHintMask 

ButtonlMotionMask 

Button2MotionMask 

ButtonSMotionMask 

Button4MotionMask 



No events wanted 
Keyboard down events wanted 
Keyboard up events wanted 
Pointer button down events wanted 
Pointer button up events wanted 
Pointer window entry events wanted 
Pointer window leave events wanted 
Pointer motion events wanted 
Pointer motion hints wanted 

Pointer motion while button 1 down 
Pointer motion while button 2 down 
Pointer motion while button 3 down 
Pointer motion while button 4 down 
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Event Mask 


Circumstances 


ButtonSMotionMask 


Pointer motion while button 5 down 


ButtonMbtionMask 


Pointer motion while any button down 


KeymapStateMask 


Keyboard state wanted at window entry and 




focus in 


ExposureMask 


Any exposure wanted 


Visibili- 


Any change in visibility wanted 


tyChangeMask 




Struct ureNotifyMask 


Any change in window structure wanted 


ResizeRedirectMask 


Redirect resize of this window 


SubstructureNo- 


Substructure notification wanted 


tifyMask 




Substruc- 


Redirect structure requests on children 


tureRedirectiMask 




FocusChangeMask 


Any change in input focus wanted 


PropertyChangeMask 


Any change in property wanted 


ColonnapChangeMask 


Any change in colormap wanted 


OwnerGrabButtonMask 


Automatic grabs should activate with 




owner_events set to True 
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The event reported to a client application during event processing depends on 
which event masks you provide as the event-mask attribute for a window. For 
some event masks, there is a one-to-one correspondence between the event 
mask constant and the event type constant. For example, if you pass the event 
mask ButtonPressMask, the XWIN server sends back only ButtonPress events. 
Most events contain a time member, which is the time at which an event 
occurred. 

In other cases, one event mask constant can map to several event type constants. 
For example, if you pass the event mask SubstmictureNotifyMask, the XwiN 
server can send back CirculateNotify, Conf igureNotify, CreateNotify, 
DestroyNotify, GravityNotify, MapNotify, ReparentNotify, or UnraapNo- 
tify events. 

In another case, two event masks can map to one event type. For example, if 
you pass either PointerMotionMask or ButtonMotionMask, the XwiN server 
sends back a MotionNotify event. 

The following table lists the event mask, its associated event type or types, and 
the structure name associated with the event tj^. Some of these structures 
actually are typedefs to a generic structure that is shared between two event 
types. Note that N.A. appears in columns for which the information is not 
applicable. 



Event Mask Event Type Structure Generic Structure 

ButtonMotionMask MotionNotify XPointerMovedEvent XMotionEvent 

ButtonlMotionMask 

Button2MotiQnMask 

Button3MotionMask 

Button4MotionMask 

ButtonSMotionMask 

ButtonPressMask ButtonPress XButtonPressedEvent XButtonEvent 

ButtonReleaseMask ButtonRdease XButtonRdeasedEvent XButtonEvent 

ColormapChangeMa^ ColonnapNotify XColonnapEvent 

EnterWindowMask EnterNotify XEnterWindowEvent XCrossingEvent 
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Event Mask 


event type 


Structure 


Generic Structure 




vAsavci^i/uiy 


TViiASa vc T V uiuiJ TV Jul veil 1 


yV\M>l U8>9111^EiVclll 


ExposureMask 


Expose 


XExposeEvent 




CCCranhicsExDosures in CC 










NoExpose 


XNoExposeEvent 




FocusChangeMask 


Focusin 


XFocusInEvent 


XFocusQiangeEvent 




FocusOut 


XFocusOutEvent 


XFocusQiangeEvent 


KeymapStateMask 


KeymapNotify 


XKeymapEvent 




KeyPressMask 


KeyPress 


XKeyPressedEvent 


XKeyEvent 


KeyRdeaseMask 


Key Release 


XKeyReleasedEvent 


XKeyEvent 


OwnerGrabButtonMask 


Nj\. 


N.A. 




PointerMotionMask 


MotionNotify 


XPointerMovedEvent 


XMotionEvent 


PointerMotionHintMask 


N.A. 


N.A. 




PropertyChangeMask 


PropertyNotify 


XPropertyEvent 




JXC9li^d\CViUl CVUVldS^ 


12 MSI 7£k1?<VT1 f OCf 
lVtAl/<CJ\iAJUC9t 






StructureNotifyMask 


QrculateNotify 


XQrculateEvent 






ConfigureNotify 


XConfigureEvent 






DestroyNotify 


XDestroyWindowEvent 






GravityNotify 


XGravityEvent 






MapNotify 


XMapEvent 






ReparentNotify 


XReparentEvent 






UnmapNotify 


XUnmapEvent 




SubstructureNotifyMask 


QrculateNotify 


XQrculateEvent 






ConfigureNotify 


XG>nfigureEvent 






CreateNotify 


XQeateWindowEvent 






DestroyNotify 


XDestroyWindowEvent 






GravityNotify 


XGravityEvent 






MapNotify 


XMapEvent 






ReparentNotify 


XReparentEvent 
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Event Mask 


Event Type 


Structure Generic Structure 




UnmapNotify 


XUnmapEvent 


SubstructureRediredMask 


QrculateRequest 


XQrculateRequestEvent 




ConfigureRequest 


XConfigureRequestEvent 




MapRecjuest 


XMapRequestEvent 


Nj\. 


QientMessage 


XGientMessageEvent 


NA. 


MappingNotify 


XMappingEvent 


Nj\. 


SelectionQear 


XSelectk>nClearEvent 


N.A. 


SdectionNotify 


XSelectionEvent 


Nj\. 


SdectionRequest 


XSelectionRequestEvent 


VisibilityChangeMask 


VisibilityNotify 


XVisibilityEvent 



The sections that follow describe the processing that occurs when you select the 
different event masks. The sections are organized according to these processing 
categories; 

■ Keyboard and pointer events 

■ Window crossing events 

■ Input focus events 

■ Kejonap state notification events 

■ Exposure events 

■ Window state notification events 

■ Structure control events 

■ Colormap state notification events 

■ Client communication events 
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Keyboard and Pointer Events 

This section discusses: 

■ Pointer button events 

■ Keyboard and pointer events 

Pointer Button Events 

The following describes the event processing that occurs when a pointer button 
press is processed with the pointer in some window w and when no active 
pointer grab is in progress. 

The XwiN server searches the ancestors of w from the root down, looking for a 
passive grab to activate. If no matching passive grab on the button exists, the 
XwiN server automatically starts an active grab for the client receiving the event 
and sets the last-pointer-grab time to the current server time. The effect is 
essentially equivalent to an XGrabButton with these client passed arguments: 



Argument 


Value 


w 


The event window 


eventjnask 


The client's selected pointer events on the event win- 




dow 


-pointer jnode 


GrabMcxieAsync 


keyboardjnode 


GrabModeAsync 


owner_events 


True, if the dient has selected CXmerGrabButtonMask 




on the event window, otherwise False 


confinejo 


None 


cursor 


None 



The active grab is automatically terminated when the logical state of the pointer 
has all buttons released. Clients can modify the active grab by calling XUngrab- 
Pointer and XChangeActivePointerGrab. 
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Keyboard and Pointer Events 

This section discusses the processing that occurs for the keyboard events 
KeyPress and KeyRelease and the pointer events ButtonPress, Button- 
Release, and MotionNotify. For information about the keyboard event- 
handling utilities, see Chapter 10. 

The Xwnsr server reports KeyPress or KeyRelease events to clients wanting 
inforniation about keys that logically change state. Note that these events are 
generated for all keys, even those mapped to modifier bits. The XwiN server 
reports ButtonPress or ButtonRelease events to clients wanting information 
about buttons that logically change state. 

The XwiN server reports MotionNotify events to clients wanting information 
about when the pointer logically moves. The XwiN server generates this event 
whenever the pointer is moved and the pointer motion begins and ends in the 
window. The granularity of MotionNotify events is not guaranteed, but a 
client that selects this event type is guaranteed to receive at least one event 
when the pointer moves and then rests. 

The generation of the logical changes lags the physical changes if device event 
processing is frozen. 

To receive KeyPress, KeyRelease, ButtonPress, and ButtonRelease events, 
set KeyPressMask, KeyReleaseMask, ButtonPressMask, and Button- 
ReleaseMask bits in the event-mask attribute of the window. 

To receive MotionNotify events, set one or more of the following event masks 
bits in the event-mask attribute of the window. 

■ ButtonlMotionMask-ButtonSMotionMask The client application receives 
MotionNotify events only when one or more of the specified buttons is 
pressed. 

■ ButtonMotionMask The client application receives MotionNotify events 
only when at least one button is pressed. 

■ PointerMotionMask The client application receives MotionNotify events 
independent of the state of the pointer buttons. 

■ PointerMotionHint If PointerMotionHintMask is selected, the XwiN 
server is free to send only one MotionNotify event (with the is__hint 
member of the XPointerMovedEvent structure set to NotifyHint) to the 
client for the event window, until either the key or button state changes, 
the pointer leaves the event window, or the client calls XQueryPointer or 
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XGetMotionEvents. The server still may send MotionNotify events 
without is_hint set to NbtifyHint. 

The source of the event is the viewable window that the pointer is in. The win- 
dow used by the XwiN server to report these events depends on the window's 
position in the window hierarchy and whether any intervening window prohi- 
bits the generation of these events. Starting with the source window, the XwiN 
server searches up the window hierarchy until it locates the first window 
specified by a client as having an interest in these events. If one of the interven- 
ing windows has its do-not-propagate-mask set to prohibit generation of the 
event type, the events of those types will be suppressed. Clients can modify the 
actual window used for reporting by performing active grabs and, in the case of 
keyboard events, by using the focus window. 

The structures for these event types contain: 

t:^pedef struct { 

int type; /* ButtonPresa or ButtoniRsleaM V 

tinsigxied long serial; /* # o£ last request processed by server V 
Bool sendjevent; /* true if this came from a SendBvent reqiaest V 
Display *diflplay; /* Display the event was read from */ 
Window window; /* ' 'event' ' window it is reported relative to V 

Window root; /* root window that the event occurred on */ 

Window subwindow; /* child window */ 
Tine time; /* milliseconds */ 

int X, y; /* pointer y coordinates in event window */ 

int x_root, y_root; /* coordinates relative to root */ 
unsigned int state; /* key or button mask */ 
unsigned int button; /* detail V 
Bool sane_screen; /* sane screen flag */ 
} XButtonEvent; 

typedef XButtonEvent XButtonPressedBvent; 
typedef XButtonEvent XButtonReleasedBvent; 
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typedef struct ( 



int type; 


/* 


KeyPress or KeyRelease V 


iinsignad long serial; 


/* 


# of last request processed by server */ 


Bool sendjsvent; 


/* 


true if this came from a SendEvent request */ 


Display Miiqplay; 


/* 


Diqplay the event was read from */ 


Windoir tdzKioir; 


/* 


^*event" window it is reported relative to */ 


Window root; 


/* 


root window that the event occurred on */ 


Window subwindow; 


/* 


child window */ 


Time time; 


/* 


milliseconds V 


int X, y; 


/* 


pointer x, y coordinates in event window */ 


int xjroot, yjroot; 


/* 


coordinates relative to root */ 


unsigned int state; 


/* 


key or button mask */ 


unsigned int keycode; 


/* 


detail V 


Bool sane^scsreen; 


/* 


same screen flag */ 



} XKeyBvent; 

typedef XKeyEvent XKeyPressedBvent; 
t:ypedef XECeyBvent XKeyReleasedBvent; 



struct { 






int type; 


/* 


MotionNotify */ 


unsigned long serial; 


/* 


# of last request processed by server */ 


Bool sendjevent; 


/* 


true if this came from a SendEvent request */ 


Display *di8play; 


/* 


Display the event was read from */ 


Window window; 


/* 


^ ^event' ' window reported relative to */ 


Window root; 


/* 


root window that the event occurred on */ 


Window subwindow; 


/* 


child window V 


Tins tine; 


/* 


milliseconds */ 


int X, y; 


/* 


pointer x, y coordinates in event window */ 


int xjcoot, y_root; 


/* 


coordinates relative to root */ 


unsigned int state; 


/* 


key or button mask V 


char isjiint; 


/* 


detail */ 


Bool sane_8creen; 


/* 


same screen flag */ 



} XMotionBvent; 

typedef XMotionBvent XPointerlfovedEvent; 



These structures have the following common members: window, root, subwin- 
dow, time, X, y, x_root, y_root, state, and same__screen. The window member is 
set to the window on which the event was generated and is referred to as the 
event window. As long as the conditions previously discussed are met, this is 
the window used by the XwiN server to report the event. The root member is 
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set to the source window's root window. The x_root and y__root members are 
set to the pointer's coordinates relative to the root window's origin at the time 
of the event. 

The same_screen member is set to indicate whether the event window is on the 
same screen as the root window and can be either True or False. If True, the 
event and root windows are on the same screen. If False, the event and root 
windows are not on the same screen. 

If the source window is an inferior of the event window, the subwindow 
member of the structure is set to the child of the event window that is the 
source member or an ancestor of it. Otherwise, the XwiN server sets the 
subwindow member to None. The time member is set to the time when the 
event was generated and is expressed in milliseconds. 

If the event window is on the same screen as the root window, the x and y 
members are set to the coordinates relative to the event window's origin. Oth- 
erwise, these members are set to zero. 

The state member is set to indicate the logical state of the pointer buttons and 
modifier keys just prior to the event, which is the bitwise inclusive OR of one or 
more of the button or modifier key masks: ButtonlMask, Button2Mask, 
ButtonSMask, Button4Mask, ButtonSMask, ShiftMask, LockMask, Control- 
Mask, ModlMask, Mod2Mask, ModSMask, Mod4Mask, and ModSMask. 

Each of these structures also has a member that indicates the detail. For the 
XKeyPressedEvent and XKeyReleasedEvent structures, this member is called 
keycode. It is set to a number that represents a physical key on the keyboard. 
The keycode is an arbitrary representation for any key on the keyboard (see 
Chapter 7). 

For the XButtonPressedEvent and XButtonReleasedEvent structures, this 
member is called button. It represents the pointer button that changed state and 
can be the Buttonl, Button2, Buttons, Button4, or Buttons value. For the 
XPolnterMDvedEvent structure, this member is called is_hint. It can be set to 
NotifyNontial or NotifyHint. 
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Window Entry/Exit Events 

This section describes the processing that occurs for the window crossing events 
EnterNotify and LeaveNotify. If a pointer motion or a window hierarchy 
change causes the pointer to be in a different window than before, the XWIN 
server reports EnterNotify or LeaveNotify events to clients who have 
selected for these events. All EnterNotify and LeaveNotify events caused by 
a hierarchy change are generated after any hierarchy event ( UnniapNotif y , 
MapNotify, Conf igureNotify, GravityNotify, CirculateNotify) caused by 
that change; however, the X protocol does not constrain the ordering of Enter- 
Notify and LeaveNotify events with respect to FocusOut, VisibilityNo- 
tify, and E^qpose events. 

This contrasts with MotionNotify events, which are also generated when the 
pointer moves but only when the pointer motion begins and ends in a single 
window. An EnterNotify or LeaveNotify event also can be generated when 
some client application calls XGrabPointer and XUngrabPointer. 

To receive EnterNotify or LeaveNotify events, set the EnterWindowMask or 
LeaveWindowMask bits of the event-mask attribute of the window. 

The structure for these event types contains: 
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typedef struct ( 



int type; 


/* 


Bnterilotify or LeaveNotify */ 


unsigned long aerial; /* 


# of last request processed 1^ server */ 


Bool Mcidjsvmt; 


/* 


true if this came from a SendBvent request */ 


Display *di8play; 


/* 


Display the event was read from */ 


Windbw window; 


/* 


^ ^event' ' window reported relative to */ 


Window root; 


/* 


root window that the event occurred on */ 


Window subwindow; 


/* 


child window */ 


Time tine; 


/* 


milliseconds */ 


int X, y; 


/* 


pointer x, y coordinates in event window */ 


int xjroot, y^root; 


/* 


coordinates relative to root */ 


int node; 


/* 


Noti^ormal, NbtifyGrab, WbtifyUngrab */ 


int detail; 








* MbtifyAncestor, NotifyVirtual, Notifylnferior, 




* MbtifyNonlinear.NotifyNonlinearVirtual 
*/ 


Bool aane_8cxeen; 


/* 


sane screen flag */ 


Bool focus; 


/* 


boolean focus */ 


unsigned int state; 


/* 


key or button nask */ 



> XCrossingBvent; 

typedef XCrossingBveht XBnterWindoi£vent; 
typedef XCrossin^fBvent XLeaveWindovBvent; 

The window member is set to the window on which the EnterNotify or 
LeaveNotify event was generated and is referred to as the event window. This 
is the window used by the XwiN server to report the event, and is relative to the 
root window on which the event occurred. The root member is set to the root 
window of the screen on which the event occurred. 

For a LeaveNotify event, if a child of the event window contains the initial 
position of the pointer, the subwindow component is set to that child. Other- 
wise, the XwiN server sets the subwindow member to None. For an EnterNo- 
tify event, if a child of the event window contains the final pointer position, 
the subwindow component is set to that child or None. 

The time member is set to the time when the event was generated and is 
expressed in milliseconds. The x and y members are set to the coordinates of 
the pointer position in the event window. This position is always the pointer's 
final position, not its initial position. If the event window is on the same screen 
as the root window, x and y are the pointer coordinates relative to the event 
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window's origin. Otherwise, x and y are set to zero. The x_root and y_root 
members are set to the pointer's coordinates relative to the root window's origin 
at the time of the event. 

The same_screen member is set to indicate whether the event window is on the 
same screen as the root window and can be either True or False. If True, the 
event and root windows are on the same screen. If False, the event and root 
windows are not on the same screen. 

The focus member is set to indicate whether the event window is the focus win- 
dow or an inferior of the focus window. The XwiN server can set this member 
to either True or False. If True, the event window is the focus window or an 
inferior of the focus window. If False, the event window is not the focus win- 
dow or an inferior of the focus window. 

The state member is set to indicate the state of the pointer buttons and modifier 
keys just prior to the event. The XwiN server can set this member to the bitwise 
inclusive OR of one or more of the button or modifier key masks: ButtonlMask, 
Button2Mask, ButtonSMask, Button4Mask, ButtonSMask, Shif tJ^sk, Lock- 
Mask, ControlMask, ModlMask, Mod2Mask, ModSMask, Mod4Mask, ModSMask. 

The mode member is set to indicate whether the events are normal events, 
pseudo-motion events when a grab activates, or pseudo-motion events when a 
grab deactivates. The XwiN server can set this member to NotifyNorinal, 
Notl£yGrab, or Noti£yUngrab. 

The detail member is set to indicate the notify detail and can be NotifyAnces- 
tor, NotifyVirtual, Notify Inferior, NotifyNonlinear, or Notif:^on- 
linearVirtual. 

Normal Entry/Exit Events 

EnterNotify and LeaveNotify events are generated when the pointer moves 
from one window to another window. Normal events are identified by XEn- 
terWindowEvent or XLeaveWindowEvent structures whose mode member is set 
to NotifyNomal. 

■ When the pointer moves from window A to window B and A is an infe- 
rior of B, the XwiN server does the following: 
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- It generates a LeaveNotify event on window A, with the detail 
member of the XLeaveWindowEvent structure set to 
NotifyAncestor. 

- It generates a LeaveNotify event on each window between win- 
dow A and window B, exclusive, with the detail member of each 
XLeaveWindowEvent structure set to NotifyVirtual. 

- It generates an EnterNotif y event on window B, with the detail 
member of the XEnterWindowEvent structure set to Notifylnfe- 
rior. 

■ When the pointer moves from window A to window B and B is an infe- 
rior of A, the XwiN server does the following: 

- It generates a LeaveNotify event on window A, with the detail 
member of the XLeaveWindowEvent structure set to 
Notifylnferior. 

- It generates an EnterNotif y event on each window between 
window A and window B, exclusive, with the detail meniber of 
each XEnterWindowEvent structure set to NotifyVirtual. 

- It generates an EnterNotify event on window B, with the detail 
member of the XEnterWindowEvent structure set to 
NotifyAncestor. 

■ When the pointer moves from window A to window B and window C is 
their least common ancestor, the XwiN server does the following: 

- It generates a LeaveNotify event on window A, with the detail 
member of the XLeaveWindowEvent structure set to 
NotifyNonlinear. 

- It generates a LeaveNotify event on each window between win- 
dow A and window C, exclusive, with the detail member of each 
XLeaveWindowEvent structure set to NotifyNonlinearVirtual. 

- It generates an EnterNotify event on each window between 
window C and window B, exclusive, with the detail member of 
each XEnterWindowEvent structure set to 

Not if ^onlinearVirtiaal . 
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- It generates an EnterNotify event on window B, with the detail 
member of the XEnterWindowEvent structure set to 
NotifyNonlinear. 

■ When the pointer moves from window A to window B on different 
screens, the XwiN server does the following: 

- It generates a LeaveNotify event on window A, with the detail 
member of the XLeaveWindowEvent structure set to 
NotifyNonlinear. 

- If window A is not a root window, it generates a LeaveNotify 
event on each window above window A up to and including its 
root, with the detail member of each XLeaveWindowEvent struc- 
ture set to NotifyNonlinearVirtual. 

- If window B is not a root window, it generates an EnterNotify 
event on each window from window B's root down to but not 
including window B, with the detail member of each XEnterWin- 
dowEvent structure set to NotifyNonlinearVirtual. 

- It generates an EnterNotify event on window B, with the detail 
member of the XEnterWindowEvent structure set to 
NotifyNonlinear. 

Grab and Ungrab Entry/Exit Events 

Pseudo-motion mode EnterNbtify and LeaveNotify events are generated 
when a pointer grab activates or deactivates. Events in which the pointer grab 
activates are identified by XEnterWindowEvent or XLeaveWindowEvent struc- 
tures whose mode member is set to NotifyGrab. Events in which the pointer 
grab deactivates are identified by XEnterWindowEvent or XLeaveWindowEvent 
structures whose mode member is set to NotifyUngrab (see XGrabPointer). 

■ When a pointer grab activates after any initial warp into a confine_to win- 
dow and before generating any actual ButtonPress event that activates 
the grab, G is the grab_window for the grab, and P is the window the 
pointer is in, the XwiN server does the following: 

~ It generates EnterNotify and LeaveNotify events (see "Normal 
Entry/Exit Events" in this chapter), with the mode members of 
the XEnterWindowEvent and XLeaveWindowEvent structures set 
to NotifyGrab. These events are generated as if the pointer 
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were to suddenly warp from its current position in P to some 
position in G. However, the pointer does not warp, and the 
XwiN server uses the pointer position as both the initial and final 
positions for the events. 

■ When a pointer grab deactivates after generating any actual Button- 
Release event that deactivates the grab, G is the grab_window for the 
grab, and P is the window the pointer is in, the XwiN server does the fol- 
lowing: 

- It generates EnterNotify and LeaveNbtify events (see ''Normal 
Entiy/Exit Events" in this chapter), with the mode members of 
the XEnterWindowEvent and XLeaveWindowEvent structures set 
to NotifyUngrab. These events are generated as if the pointer 
were to suddenly warp from some position in G to its current 
position in P. However, the pointer does not warp, and the 
XwiN server uses the current pointer position as both the initial 
and final positions for the events. 



Input Focus Events 

This section describes the processing that occurs for the input focus events 
Focusin and FocusOut. The XwiN server can report Focusin or FocusOut 
events to clients wanting information about when the input focus changes. The 
keyboard is always attached to some window (typically, the root window or a 
top-level window), which is called the focus window. The focus window and 
the position of the pointer determine the window that receives keyboard input. 
Clients may need to know when the input focus changes to control highlighting 
of areas on the screen. 

To receive Focusin or FocusOut events, set the FocusChangeMask bit in the 
event-mask attribute of the window. 

The structure for these event types contains: 
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typedef struct { 
int type; 

unsigned long serial; 
Bool sendjsvent; 
Display MisplAy; 
Window window; 
int node; 
int detail; 



/* Focuslh or FoousCXst V 

/* # of last request processed by server */ 

/* true if this came from a SendEvent request */ 

/* Display the event was read from */ 

/* window of event */ 

/* NotifyHormal, NotifyGrab, Notifyltograb */ 



/* 

* NbtifyAncestor, Noti^Virtual, Notifylnferior, 

* NotifyNonlinear,NotifyNonlinearVirtual, Notif:^ointer, 

* Notif^ointedtoot, NotifyDetailNone 
*/ 



} XFocusChangeBvent; 

typedef XFocusChangeEvent XFocusInBvent; 
typedef XFocusChangeBvent XFocusOutEvent; 

The window member is set to the window on which the Focusin or FocusOut 
event was generated. This is the window used by the XwiN server to report the 
event. The mode member is set to indicate whether the focus events are normal 
focus events, focus events while grabbed, focus events when a grab activates, or 
focus events when a grab deactivates. The XwiN server can set the mode 
member to NotifyNornal, NotifyWhileGrabbed, NotifyGrab, or 
NotifyUngrab. 

All FocusOut events caused by a window unmap are generated after any 
UnmapNotify event; however, the X protocol does not constrain the ordering of 
FocusOut events with respect to generated EnterNbtify, LeaveNotify, Visi- 
bilityNotify, and Ea^se events. 

Depending on the event mode, the detail member is set to indicate the notify 
detail and can be NotifyAnoestor, NotifyVirtual, Notifyinf erior, 
NotifyNonlinear, NotifyNonlinearVirtual, NotifyPointer, NotifyPoin- 
terRoot, or NotifyDetailNone. 
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Normal Focus Events and Focus Events While Grabbed 

Normal focus events are identified by XFocusInEvent or XFocusOutEvent 
structures whose mode member is set to NotifyNoianal. Focus events while 
grabbed are identified by XFocusInEvent or XFocusOutEvent structures whose 
mode member is set to NotifyWhileGrabbed. The XWIN server processes nor- 
mal focus and focus events while grabbed according to the following: 

■ When the focus moves from window A to window B, A is an inferior of 
B, and the pointer is in window P, the XwiN server does the following: 

- It generates a FocusOut event on window A, with the detail 
member of the XFocusOutEvent structure set to NotifyAnces- 
tor. 

~ It generates a FocusOut event on each window between window 
A and window B, exclusive, with the detail member of each 
XFocusOutEvent structure set to NotifyVirtual. 

- It generates a Focusin event on window B, with the detail 
member of the XFocusOutEvent structure set to 
Notifylnferior. 

- If window P is an inferior of window B but window P is not 
window A or an inferior or ancestor of window A, it generates a 
Focusin event on each window below window B, down to and 
including window P, with the detail member of each 
XFocusInEvent structure set to NotifyPointer. 

■ When the focus moves from window A to window B, B is an inferior of 
A, and the pointer is in window P, the XwiN server does the following: 

- If window P is an inferior of window A but P is not an inferior 
of window B or an ancestor of B, it generates a FocusOut event 
on each window from window P up to but not including win- 
dow A, with the detail member of each XFocusOutEvent struc- 
ture set to NotifyPointer. 

- It generates a FocusOut event on window A, with the detail 
member of the XFocusOutEvent structure set to 
Notifylnferior . 
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- It generates a Focusin event on each window between window 
A and window B, exclusive, with the detail member of each 
XFcxjusInEvent structure set to NotifyVirtual. 

- It generates a Focusin event on window B, with the detail 
member of the XFocusInEvent structure set to NotifyAncestor. 

■ When the focus moves from window A to window B, window C is their 
least common ancestor, and the pointer is in window P, the XwiN server 
does the following: 

- If window P is an inferior of window A, it generates a FocusOut 
event on each window from window P up to but not including 
window A, with the detail member of the XFocusCXitEvent 
structure set to NotifyPointer. 

- It generates a FocusOut event on window A, with the detail 
member of the XFocusOutEvent structure set to Notif yNon- 
linear. 

- It generates a FocusOut event on each window between window 
A and window Q exclusive, with the detail member of each 
XFocusOutEvent structure set to NotifyNonlinearVirtual. 

- It generates a Focusin event on each window between C and B, 
exclusive, with the detail member of each XFocusInEvent struc- 
ture set to NotifyNonlinearVirtual. 

- It generates a Focusin event on window B, with the detail 
member of the XFocusInEvent structure set to NotifyNon- 
linear. 

- If window P is an inferior of window B, it generates a Focusin 
event on each window below window B down to and including 
window P, with the detail member of the XFocusInEvent struc- 
ture set to NotifyPointer. 

■ When the focus moves from window A to window B on different screens 
and the pointer is in window P, the XwiN server does the following: 

- If window P is an inferior of window A, it generates a FocusOut 
event on each window from window P up to but not including 
window A, with the detail member of each XFocusOutEvent 
structure set to NotifyPointer. 
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- It generates a FocusOut event on window A, with the detail 
member of the XFocusOutEvent structure set to NotifyNon- 
linear. 

- If window A is not a root window, it generates a FocusOut 
event on each window above window A up to and including its 
root, with the detail member of each XFocusCXitEvent structure 
set to NotifyNonlinearVirtual. 

- If window B is not a root window, it generates a Focusin event 
on each window from window B's root down to but not includ- 
ing window B, with the detail member of each XFocusInEvent 
structure set to NotifyNonlinearVirtual. 

- It generates a Focusin event on window B, with the detail 
member of each XFocusInEvent structure set to Notif^on- 
linear. 

~ If window P is an inferior of window B, it generates a Focusin 
event on each window below window B down to and including 
window P, with the detail member of each XFocusInEvent 
structure set to NotifyPointer. 

■ When the focus moves from window A to PointerRoot (events sent to 
the window under the pointer) or None (discard), and the pointer is in 
window P, the XwiN server does the following: 

- If window P is an inferior of window A, it generates a FocusOut 
event on each window from window P up to but not including 
window A, with the detail member of each XFocusOutEvent 
structure set to NotifyPointer. 

- It generates a FocusOut event on window A, with the detail 
member of the XFocusOutEvent structure set to NotifyNon- 
llnear. 

- If window A is not a root window, it generates a FocusOut 
event on each window above window A up to and including its 
root, with the detail member of each XFocusOutEvent structure 
set to NotifyNonlinearVirtual. 
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- It generates a Focusin event on the root window of all screens, 
with the detail member of each XFocusInEvent structure set to 
NotifyPointerRoot (or NotifyDetailNone). 

- If the new focus is PointerRoot, it generates a Focusin event 
on each window from window Ps root down to and including 
window P, with the detail member of each XFocusInEvent 
structure set to NotifyPointer. 

When the focus moves from PointerRoot (events sent to the window 
under the pointer) or None to window A, and the pointer is in window P, 
the XWIN server does the following: 

- If the old focus is PointerRoot, it generates a FocusOut event 
on each window from window P up to and including window 
P's root, with the detail member of each XFocusOutEvent struc- 
ture set to NotifyPointer. 

- It generates a FocusOut event on all root windows, with the 
detail member of each XFocusOutEvent structure set to 
NotifyPointerRoot (or NotifyDetailNone). 

- If window A is not a root window, it generates a Focusin event 
on each window from window A's root down to but not includ- 
ing window A, with the detail member of each XFocusInEvent 
structure set to Notif:^onlinearVirtual. 

- It generates a Focusin event on window A, with the detail 
meniber of the XFocusInEvent structure set to NotifyNon- 
linear. 

- If window P is an inferior of window A, it generates a Focusin 
event on each window below window A down to and including 
window P, with the detail member of each XFocusInEvent 
structure set to NotifyPointer. 

When the focus moves from PointerRoot (events sent to the window 
under the pointer) to None (or vice versa), and the pointer is in window P, 
the XwiN server does the following: 
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- If the old focus is PointerRoot, it generates a FocusOut event 
on each window from window P up to and including window 
Fs root, with the detail member of each XFocusOutEvent struc- 
ture set to NotifyPointer. 

- It generates a FocusOut event on all root windows, with the 
detail member of each XFocusOutEvent structure set to either 
NotifyPointerRoot or Notif^etailNone. 

- It generates a Focusin event on all root windows, with the 
detail member of each XFocusInEvent structure set to 
NotifyDetailNone or NotifyPointerRoot. 

~ If the new focus is PointerRoot, it generates a Focusin event 
on each window from window P's root down to and including 
window P, with the detail member of each XFocusInEvent 
structure set to NotifyPointer. 

Focus Events Generated by Grabs 

Focus events in which the keyboard grab activates are identified by 
XFocusInEvent or XFocusOutEvent structures whose mode member is set to 
NotifyGrab. Focus events in which the keyboard grab deactivates are 
identified by XFocusInEvent or XFocusOutEvent structures whose mode 
member is set to NotifyUngrab (see XGrabKeyboard). 

■ When a keyboard grab activates before generating any actual KeyPress 
event that activates the grab, G is the grab window, and F is the current 
focus, the XWIN server does the following: 

- It generates Focusin and FocusOut events, with the mode 
members of the XFocusInEvent and XFocusOutEvent structures 
set to NotifyGrab. These events are generated as if the focus 
were to change from F to G. 

■ When a keyboard grab deactivates after generating any actual 
KeyRelease event that deactivates the grab, G is the grab^window, and F 
is the current focus, the XwiN server does the following: 

- It generates Focusin and FocusOut events, with the mode 
members of the XFocusInEvent and XFocusOutEvent structures 
set to NotifyUngrab. These events are generated as if the focus 
were to change from G to F. 
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Key Map State Notification Events 

The XwiN server can report KeyinapNotify events to clients that want informa- 
tion about changes in their keyboard state. 

To receive KeyinapNotify events, set the KeyniapStateMask bit in the event- 
niask attribute of the window. The XwiN server generates this event immedi- 
ately after every EnterNotify and Focusin event. 

The structure for this event type contains: 

/* generated on BnterWindoir and Focusin When KeynsapState selected */ 
typedef struct { 

int type; /* IteymapNotil^ */ 

\2n8igned long serial; /* # of last request processed by server */ 
Bool sendjBvent; /* true if this came from a SendEvent request */ 

Display *di8play; /* Display the event was read from */ 

Window window; 
char keyjvector[32] ; 
} XECeyms^vent; 

The window member is not used but is present to aid some toolkits. The 
key_vector member is set to the bit vector of the keyboard. Each bit set to 1 
indicates that the corresponding key is currently pressed. The vector is 
represented as 32 bytes. Byte N (from 0) contains the bits for keys 8N to 8N + 7 
with the least-significant bit in the b5^e representing key 8N. 



Exposure Events 

The X protocol does not guarantee to preserve the contents of window regions 
when tiie windows are obscured or reconfigured. Some implementations may 
preserve the contents of windows. Other implementations are free to destroy 
the contents of windows when exposed. X expects client applications to assume 
the responsibility for restoring the contents of an exposed window region. (An 
exposed window region describes a formerly obscured window whose region 
becomes visible.) Therefore^ the XwiN server sends Expose events describing the 
window and the region of the window that has been exposed. A naive client 
application usually redraws the entire window. A more sophisticated client 
application redraws only the exposed region. 
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Expose Events 

The XwiN server can report E3q>ose events to clients wanting information about 
when the contents of window regions have been lost. The circumstances in 
which the XwiN server generates Expose events are not as definite as those for 
other events. However, the XwiN server never generates Esqpose events on win- 
dows whose class you specified as Ir^utOnly. The XwiN server can generate 
Expose events when no valid contents are available for regions of a window 
and either the regions are viable, the regions are viewable and the server is 
(perhaps newly) maintaining backing store on the window, or the window is 
not viewable but the server is (perhaps newly) honoring the window's backing- 
store attribute of Always or WhenMapped. The regions decompose into an (arbi- 
trary) set of rectangles, and an E^qpose event is generated for each rectangle. 
For any given window, the XwiN server guarantees to report contiguously all of 
the regions exposed by some action that causes Expose events, such as raising a 



To receive Expose events, set the ExposureMask bit in the event-mask attribute 
of the window. 

The structure for this event type contains: 
typedef struct ( 



> XBxpoMBvsnt; 

The window member is set to the exposed (damaged) window. The x and y 
members are set to the coordinates relative to the window's origin and indicate 
the upper-left comer of the rectangle. The width and height members are set to 
the size (extent) of the rectangle. The count member is set to the number of 
Expose events that are to follow. If count is zero, no more Es^se events fol- 
low for this window. However, if count is nonzero, at least that number of 
Expose events (and possibly more) follow for this window. Simple applications 
that do not want to optimize redisplay by distinguishing between subareas of its 



window. 



Int typm; 

unsigned long aeriiil; 
Bool sendjiVMit; 
Diqpliy Miqplay; 
Windov window; 
int X, y; 

int width, teight; 
int oount; 



/* Bxpoflo V 

/* # of last request processed by server */ 

/* true if this cane from a SendBvent reqpest */ 

/* Display the event was read from */ 



/* if nonzero, at least this mai^ more */ 
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window can just ignore all Expose events with nonzero counts and perform full 
redisplays on events with zero counts. 

GraphicsExpose and NoExpose Events 

The XWIN server can report GraphicsExpose events to clients wanting informa- 
tion about when a destination region could not be computed during certain 
graphics requests: XCopyArea or XCopyPlane. The XwiN server generates this 
event whenever a destination region could not be computed due to an obscured 
or out-of-bounds source region. In addition, the XwiN server guarantees to 
report contiguously all of the regions exposed by some graphics request (for 
example, copying an area of a drawable to a destination drawable). 

The XwiN server generates a NoExpose event whenever a graphics request that 
might produce a GraphicsE^qpose event does not produce any. In other words, 
the client is really asking for a GraphicsExpose event but instead receives a 
NoExpose event. 

To receive GraphicsExpose or NoExpose events, you must first set the 
graphics-exposure attribute of the graphics context to True. You also can set 
the graphics-expose attribute when creating a graphics context using XCreateGC 
or by calling XSetGraphicsExposures. 

The structures for these event types contain: 

typedef struct { 

Int type; /* Gr^^hiosEs^sa */ 

luisigned long aerial; /* # of last request processed by server */ 

Bool sendjevent; /* true if this cane from a SendEvent request */ 

Di^lay *di«play; /* Display the event was read from */ 
Drawable drawable; 
int X, y; 

int width, hei^t; 

int count; /* if nonzero, at least this many more */ 
int major_oode; core is CopyArea or CopyPlane */ 

int minor_oode; /* not defined in the core */ 
} XGriqphioaBxposeBvent; 
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typedef struct { 
int type; 

unsigned long serial; 
Bool sendjsvisnt; 
Display *display; 
Drawable drawable; 
int najor^oode; 
int minor oode; 



/* NoExpose */ 

/* # of last request processed by server */ 

/* true if this cana from a SendBvent request V 

/* Di^lay the event was read from */ 



/* core is CopyArea or CopyPlane */ 
/* not defined in the core */ 



} XNdSxpos^vent; 

Both structures have these common members: drawable, major^code, and 
minor_code. The drawable member is set to the drawable of the destination 
region on which the graphics request was to be performed. The major^oode 
member is set to the graphics request initiated by the client and can be either 
XjCopyArea or XjCopyPlane. If it is XjGopyArea, a call to XCopyArea initiated 
the request. If it is X_CopyPlane, a call to XCopyPlane initiated the request. 
These constants are defined in < Xll/Xproto.h >. The minor_code member, 
like the nuijor jcode member, indicates which graphics request was initiated by 
the client. However, the minor_code member is not defined by the core X proto- 
col and will be zero in these cases, although it may be used by an extension. 

The XGraphicsExposeEvent structure has these additional members: x, y, 
width, height, and coimt. The x and y members are set to the coordinates rela- 
tive to the drawable's origin and indicate the upper-left comer of the rectangle. 
The width and height members are set to the size (extent) of the rectangle. The 
count member is set to the number of GraphicsExpose events to follow. If 
count is zero, no more GraphicsE:qpose events follow for this window. How- 
ever, if count is nonzero, at least that number of GraphicsExpose events (and 
possibly more) are to follow for this window. 



Window State Change Events 



The following sections discuss: 
■ Circulat6Noti£y events 



■ Conf igureNotify events 
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■ CreateNotify events 

■ DestroyNotify events 

■ GravityNotify events 

■ MapNoti£y events 

■ Mapping^otify events 

■ ReparentNotlfy events 

■ UnniapNotify events 

■ VisibilityNotify events 



CirculateNotify Events 

The XWIN server can report CirculateNotify events to clients wanting infor- 
mation about when a window changes its position in the stack. The XwiN 
server generates this event type whenever a window is actually restacked as a 
result of a dient application caUing XCirculateSubwindows, 
XCirculateSubwindowsUp, or XCirculateSubwindowsDown. 

To receive CirculateNotify events, set the StructureNotifyMask bit in the 
event-mask attribute of the window or the SubstructureNotifyMask bit in the 
event-mask attribute of the parent window (in which case, circulating any child 
generates an event). 

The structure for this event type contains: 

typedef struct { 

int type; /* CircuUteMotify V 

unsigned long serial; /* # of last request processed by server */ 

Bool sendjevent; /* true if this came from a SendEvent request */ 

Display ^display; /* Display the event was read from */ 

Window event; 
Window window; 

int place; /* PlaceOnTqp, PlaceOnBottom */ 

> XCirculateBvent; 
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The event member is set either to the restacked window or to its parent, 
depending on whether StructureNotify or SubstructxireNotify was 
selected. The window member is set to the window that was restacked. The 
place member is set to the window's position after the restack occurs and is 
either PlaceOnTop or PlaceOnBottom. If it is PlaceOnTop, the window is now 
on top of all siblings. If it is PlaoeOnBottcxn, the window is now below all 
siblings. 

ConfigureNotify Events 

The XwiN server can report ConfigureNotify events to clients wanting infor- 
mation about actual changes to a window's state, such as size, position, border, 
and stacking order. The XwiN server generates tfiis event type whenever one of 
the following configure window requests made by a client application actually 
completes: 

■ A window's size, position, border, and/or stacking order is reconfigured 
by calling XConf igureWindow. 

■ The window's position in the stacking order is changed by calling 
XLowerWindow, XRaiseWindow, or XRestackWindows. 

■ A window is moved by calling XMoveWindow. 

■ A window's size is changed by calling XResizeWindow. 

■ A window's size and location is changed by calling XMoveResizeWindow. 

■ A window is mapped and its position in the stacking order is changed by 
calling XMapRaised. 

■ A window's border width is changed by calling XSetWindowBor- 
derWidth. 

To receive ConfigureNotify events, set the StructureNotifyMask bit in the 
event-mask attribute of the window or the SubstructureNotifyMask bit in the 
event-mask attribute of the parent window (in which case, configuring any child 
generates an event). 

The structure for this event type contains: 
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typediBf struct ( 
int type; 

unsigned long aerial; 
Bool sendjavent; 
Display Misplay; 
Window event ; 
Window trindow; 
int X, y; 

int width, bei^t; 
int borderjridth; 
Window above; 
Bool override_redirect; 
} XConfigureEvent; 

The event member is set either to the reconfigured window or to its parent, 
depending on whether StructureNoti^ or SubstructureNotify was 
selected. The window member is set to the window whose size, position, 
border, and/or stacking order was changed. 

The X and y members are set to the coordinates relative to the parent window's 
origin and indicate the position of the upper-left outside comer of the window. 
The width and height members are set to the inside size of the window, not 
including the border. The border_width member is set to the width of the 
window's border, in pixels. 

The above member is set to the sibling window and is used for stacking opera- 
tions. If the XWIN server sets this member to None, the window whose state 
was changed is on the bottom of the stack with respect to sibling windows. 
However, if this member is set to a sibling window, the window whose state 
was changed is placed on top of this sibling window. 

The override_redirect member is set to the override-redirect attribute of the win- 
dow. Window manager clients normally should ignore this window if the 
override_redirect member is True. 



/* Conf iguxeNotii^ V 

/* # of last request processed by server */ 

/* true if tbis came from a SendBvent request */ 

/* Diqplay tbe event was read from V 
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CreateNotify Events 

The XwiN server can report CreateNotify events to clients wanting informa- 
tion about creation of windows. The XwiN server generates this event whenever 
a client application creates a window by calling XCreateWindow or XCreateSini:- 
pleWindow. 

To receive CreateNotify events, set the SubstructureNotifyMask bit in the 
event-mask attribute of the window. Creating any children then generates an 
event. 

The structure for the event type contains: 
typedaf stziict { 



int type; 


/* 


CreateNotify */ 


unsigned long serial; 


/* 


# of last request processed server */ 


Bool awndjBvmt; 


/* 


true if this cane from a SendEvent reqiiest */ 


Display *display; 


/* 


Display the event was read from */ 


Window parent; 


/* 


parent of the window */ 


Window window; 


/* 


window id of window created */ 


int X, y; 


/* 


window location */ 


int width, height; 


/* 


size of trindow */ 


int borderjuidth; 


/* 


border width V 


Bool ovexridejcedirect; 


/* 


creation should be overridden */ 



} XCreateWindoKBvent; 

The parent member is set to the created window's parent The window member 
specifies the created window. The x and y members are set to the created 
window's coordinates relative to the parent window's origin and indicate the 
position of the upper-left outside comer of the created window. The width and 
height members are set to the inside size of the created window (not including 
the border) and are always nonzero. The border_width member is set to the 
width of the created window's border, in pixels. The override_redirect member 
is set to the override-redirect attribute of tite vyandow. Window manager clients 
normally should ignore this window if the override_redirect member is True. 
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DestroyNotify Events 

The XWIN server can report DestroyNotify events to dients wanting informa- 
tion about which windows are destroyed. The XwiN server generates this event 
whenever a client application destroys a window by calling XDestroyWindow or 
XDest roySubiirindows . 

The ordering of the DestroyNotify events is such that for any given window, 
DestroyNotify is generated on all inferiors of the window before being gen- 
erated on the window itself. The X protocol does not constrain the ordering 
among siblings and across subhierarchies. 

To receive DestroyNotify events, set the StructureNotifyMask bit in the 
event-mask attribute of the window or the SubstructureNbtifyMask bit in the 
event-mask attribute of the parent window (in which case, destroying any child 
generates an event). 

The structure for this event type contains: 

typedef struct { 

int type; /* DestroyNotify */ 

unsigned long serial; /* # of last recjuest processed by server */ 
Bool sendjevent; /* true if this cane from a SendBvent request */ 

Display Misplay; /* Display the event was read from V 

Window event; 
Window window; 
> XDestroyWindowBvent; 



The event member is set either to the destroyed window or to its parent, 
depending on whether StructureNotify or SubstructureNotify was 
selected. The window member is set to the window that is destroyed. 



GravityNotify Events 

The XwiN server can report GravityNotify events to dients wanting informa- 
tion about when a window is moved because of a change in the size of its 
parent. The XwiN server generates this event whenever a client application 
actually moves a child window as a result of resizing its parent by calling XCon- 
f igureWindow, XMoveResizeWindow, or XResizeWindow. 
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To receive GravityNotify events, set the StructureNotifyMask bit in the 
event-mask attribute of the window or the SubstructureNotif yMask bit in the 
event-mask attribute of the parent window (in which case, any child that is 
moved because its parent has been resized generates an event). 

The structure for this event type contains: 

t^^pedef struct { 
int type; 

unsigned long serial; 
Bool aendjBVBnt; 
Display Misplay; 
Window event ; 
WindUHr window; 
int X, y; 
> XGravityBvent; 

The event member is set either to the window that was moved or to its parent, 
depending on whether StructureNotify or SubstructureNotify was 
selected. The window member is set to the child window that was moved. The 
X and y members are set to the coordinates relative to the new parent window's 
origin and indicate the position of the upper-left outside comer of the window. 

MapNotify Events 

The XWIN server can report MapNotify events to clients wanting information 
about which windows are mapped. The XwiN server generates this event tj^^e 
whenever a client application changes the window's state from unmapped to 
mapped by calling XMaf^indow, XMapRaised, XMapSubwindows, XReparentWin- 
dow, or as a result of save-set processing. 

To receive MapNotify events, set the StructureNotif yMask bit in the event- 
mask attribute of the window or the SubstructureNotifyMask bit in the 
event-mask attribute of the parent window (in which case, mapping any child 
generates an event). 

The structure for this event type contains: 



/* GravityNotii* V 

/* # of last request processed by server */ 

/* true if this came fron a SendESvent request */ 

/* Display the event was read from V 
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typedaf struct { 



Int typs; 

unflign»d long serial; 
Bool smdjsvsnt; 
Diqplay Misplay; 



/* Hapilotify */ 

/* # of last rsquftst processed by server */ 

/* true if this came from a SendEvent request */ 

/* Display the event was read from */ 



Window events- 
Window window; 

Bool override_redireot; /* boolean, is override set... */ 

) XHiqpBvent; 

The event member is set either to the window that was mapped or to its parent, 
depending on whether StructureNotify or SubstructureNotify was 
selected. The window member is set to the window that was mapped. The 
override_redirect member is set to the override-redirect attribute of the window. 
Window manager clients normally should ignore this window if the override- 
redirect attribute is True, because these events usually are generated from pop- 
ups, which override structure control. 

MappingNotify Events 

The XWIN server reports MappingNotify events to all clients. There is no 
mechanism to express disinterest in this event. The XwiN server generates this 
event type whenever a client application successfully calls: 

■ XSetModifierMapping to indicate which KeyCodes are to be used as 
modifiers 

■ XChangelteiyboardMapping to change the keyboard mapping 

■ XSetPointerMapping to set the pointer mapping 

The structure for this event type contains: 
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typedftf struct ( 



Int type; 


/* 


MappingMotify V 


unsigned long serial; 


/* 


# of last request processed by server */ 


Bool sendjsvent; 


/* 


true if this came from a SendEvent request 


Display Misplay; 


/* 


Display the event was read from */ 


Window window; 


/* 


unused V 


int request; 


/* 


one of MaqppingModif ier, MappingKsyboard, 






MappingPointer */ 


int first Jceyoode; 


/* 


first keyoode */ 


int count; 


/* 


defines range of change w. first Jceycode*/ 



> XMa^ingBvent; 

The request member is set to indicate the kind of mapping change that occurred 
and can be Mappin^^todif ier, MappingK^yboard, MappingPointer. If it is 
MappingMcxiifier, the modifier mapping was changed. If it is MappingKey- 
board, the keyboard mapping was changed. If it is MappingPointer, the 
pointer button mapping was changed. The first_keycode and count members are 
set only if the request member was set to MappingKeyboard. The number in 
first_keycode represents the first number in the range of the altered mapping, 
and count represents the number of keycodes altered. 

To update the client application's knowledge of the keyboard, you should call 
XRefreshKeyboardMapping. 

ReparentNotify Events 

The XWIN server can report ReparentNotify events to clients wanting informa- 
tion about changing a window's parent The XwiN server generates this event 
whenever a client application calls XReparentWindow and tfie window is actu- 
ally reparented. 

To receive ReparentNotify events, set the StructureNotifyMask bit in the 
event-mask attribute of the window or the SubstructxireNotifyMask bit in the 
event-mask attribute of either the old or the new parent window (in which case, 
reparenting any child generates an event). 

The structure for this event type contains: 
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typedaf atruot ( 
int typ«; 

unslgiMid long Mrial; 
Bool flendjsvMit; 
Display ^dlsplay; 
Window evwit; 
Window wixidoif; 
Window parent; 
int X, y; 

Bool overrida^TMiizect; 
> XRepaz«ntBv«nt; 

The event member is set either to the reparented window or to the old or the 
new parent, depending on whether StructureNotify or SubstructureNotify 
was selected. The window member is set to the window that was reparented. 
The parent member is set to the new parent window. The x and y members are 
set to the reparented window's coordinates relative to the new parent window's 
origin and define the upper-left outer comer of the reparented window. The 
override_redirect member is set to the override-redirect attribute of the window 
specified by the window member. Window manager clients normally should 
ignore this window if the override_redirect member is True. 

UnmapNotify Events 

The XwiN server can report UnmapNotify events to clients wanting information 
about which windows are unmapped. The XwiN server generates this event 
type whenever a client application changes the window's state from mapped to 
unmapped. 

To receive UnmapNotify events, set the StructureNotifyMask bit in the event- 
mask attribute of the window or the SubstructureNotifyMask bit in the 
event-mask attribute of the parent window (in which case, unmapping any child 
window generates an event). 

The structure for this event type contains: 



/* lUvparontNotify */ 

/* # of last rsqusst procesMd by murvar */ 

/* true if this cane from a SendBvent ^eq^e8t */ 

/* Diqplay the event was zead fzon */ 
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typedftf struct { 



int type; 

unsignsd long serial; 
Bool sendjttvent; 
Display *display; 



/* UruMLpNotify */ 

/* # of last recpiMt processed by server */ 

/* trus if this oans fron a S«nd&v<ent ^eq^sst V 

/* Display the event was read from */ 



Window event ; 
Window window; 
Bool fromjoonfigure; 
} XCJnmapEvent; 

The event member is set either to the unmapped window or to its parent, 
depending on whether StructureNotify or SubstructureNotify was 
selected. This is the window used by the XwiN server to report the event. The 
window member is set to the window that was unmapped. The from_configure 
member is set to True if the event was generated as a result of a resizing of the 
window's parent when the window itself had a win _^avity of UninapGravity. 

VisibilityNotify Events 

The XwiN server can report VisibilityNotify events to clients wanting any 
change in the visibility of the specified window. A region of a window is visi- 
ble if someone looking at the screen can actually see it The XwiN server gen- 
erates this event whenever the visibility changes state. However, this event is 
never generated for windows whose class is InputOnly. 

All VisibilityNotify events caused by a hierarchy change are generated after 
any hierarchy event ( UnraapNotif y , MapNotify, Conf igureNotify, Gravi- 
tyNotify, CirculateNotify) caused by that change. Any VisibilityNotify 
event on a given window is generated before any Expose events on that win- 
dow, but it is not required that all VisibilityNotify events on all windows be 
generated before all Expose events on all windows. The X protocol does not 
constrain the ordering of VisibilityNotify events with respect to FocusOut, 
EnterNotify, and LeaveNotify events. 

To receive VisibilityNotify events, set the VisibilityChangeMask bit in the 
event-mask attribute of the window. 

The structure for this event type contains: 
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typedftf struct ( 



int typm; 

unsigned long aerial; 
Bool Mndjwuit; 
Display *diqplay; 



ViaibiltyNotify */ 
/* # of last raqyaat prooasaad by aarvwr */ 
/* trua if thia oama from a SandBvant xaqyaat */ 
/* Display tha event was read from V 



Window window; 
int state; 
} msibilityBvant; 

The window member is set to the window whose visibility state changes. The 
state member is set to the state of the window's visibility and can be Visibili- 
tyUnobscured, VislbllltyPartlallyObscured, or VlslbllltyFullyOD- 
scured. The XwiN server ignores all of a window's subwindows when deter- 
mining the visibility state of the window and processes VisibilityNotif y 
events according to the following: 

■ When the window changes state from partially obscured, fully obscured, 
or not viewable to viewable and completely unobscured, the XwiN server 
generates the event with the state member of the XVisibilityEvent 
structure set to VisibilityUnobscured. 

■ When the window changes state from viewable and completely unob- 
scured or not viewable to viewable and partially obscured, the XwiN 
server generates the event with the state member of the XVisibili- 
tyEvent structure set to VisibilityPartiallyObscured. 

■ When the window changes state from viewable and completely unob- 
scured, viewable and partially obscured, or not viewable to viewable and 
fully obscured, the XwiN server generates the event with the state member 
of ti\e XVisibilityEvent structure set to VisibilityFullyObscured. 



Structure Control Events 



This section discusses: 



■ CirculateRequest events 
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■ Con£igureRequest events 

■ MapRequest events 

■ ResizeRequest events 



CirculateRequest Events 

The XwiN server can report CirculateRequest events to clients wanting infor- 
mation about when another client initiates a circulate window request on a 
specified window. The XwiN server generates this event type whenever a client 
initiates a circulate window request on a window and a subwindow actually 
needs to be restacked. The client initiates a circulate window request on the 
window by calling XCirculateSubwindows, XCirculateSubwindowsI^, or 
XCirculateSubwindowsDown. 

To receive CirculateRequest events, set the SubstructureRedirectMask in 
the event-mask attribute of the window. Then, in the future, the circulate win- 
dow request for the specified window is not executed, and thus, any 
subwindow's position in the stack is not changed. For example, suppose a 
client application calls XCirculateSubwindowsUp to raise a subwindow to the 
top of tfie stack. If you had selected SubstructureRedirectMask on the win- 
dow, the XWN server reports to you a CirculateRequest event and does not 
raise the subwindow to the top of the stack. 

The structure for this event type contains: 

typedef struct { 

int type; /* CirculateRequest */ 

unsigned long serial; /* # of last request processed by server V 
Bool sendjevent; /* true if this came from a SendBvent request */ 

Display ^display; /* Display the event was read from */ 

Window parent; 
Window window; 

int place; /* PlaceOnTop, PlaceOnBottom */ 

} XCirculateRequestEvent; 



The parent member is set to the parent window. The window member is set to 
the subwindow to be restacked. The place member is set to what the new posi- 
tion in the stacking order should be and is either PlaceOnTop or PlaceOnBot- 
tc^. If it is PlaceOnTop, the subwindow should be on top of all siblings. If it 
is PlaceOnBottOTi, the subwindow should be below all siblings. 
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ConfigureRequest Events 

The XwiN server can report ConfigureRequest events to clients wanting infor- 
mation about when a different client initiates a configure window request on 
any child of a specified window. The configure window request attempts to 
reconfigure a window's size, position, border, and stacking order. The XwiN 
server generates this event whenever a different client initiates a configure win- 
dow request on a window by calling XConfigureWindow, XLowerWindow, 
XRaiseWindOKT, XMapRaised, XMoveResizeWindow, XMDveWindow, XResizeWin- 
dow, XRestackWindows, or XSetWindowBorderWidth. 

To receive ConfigureRequest events, set the SubstrucstureRedirectMask bit 
in the event-mask attribute of the window. ConfigureRequest events are gen- 
erated when a Conf igureWindow protocol request is issued on a child window 
by another client For example, suppose a client application calls XLowerWindow 
to lower a window. If you had selected SubstructureRedirectiMask on the 
parent window and if tiie override-redirect attribute of the window is set to 
False, the XwiN server reports a ConfigureRequest event to you and does not 
lower the specified window. 

The structure for this event type contains: 

typedet struct { 

int type; /* ConfigureRequest */ 

unsigned long serial; /* # of last request processed by server */ 
Bool sendjavent; /* true if this came from a SendBvent request */ 

Display ^display; /* Display the event was read from */ 

Window parent; 
Window window; 
int X, y; 

int width, height; 
int border jwidth; 
Window above; 

int detail; /* iUdove, Below, Toplf , Bottomlf , Opposite */ 

unsigned long value_mask; 
> XConfigureRequestEvent; 

The parent member is set to the parent window. The window member is set to 
the window whose size, position, border width, and/or stacking order is to be 
reconfigured. The value_mask member indicates which components were 
specified in the Conf igureWindow protocol request. The corresponding values 
are reported as given in the request. The remaining values are filled in from the 
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current geometry of the window, except in the case of above (sibling) and detail 
(stack-mode), which are reported as Above and None, respectively, if they are 
not given in the request. 

MapRequest Events 

The XWIN server can report MapRequest events to clients wanting information 
about a different client's desire to map windows. A window is considered 
mapped when a map window request completes. The XwiN server generates 
this event whenever a different client initiates a map window request on an 
unmapped window whose override^redirect meniber is set to False. Clients 
initiate map window requests by calling XMapWlndow, XMapRalsed, or XMap- 
Subwlndows. 

To receive MapRequest events, set the SubstructureRedlrectMask bit in the 
event-mask attribute of the window. This means another client's attempts to 
map a child window by calling one of the map window request functions is 
intercepted, and you are sent a MapRequest instead. For example, suppose a 
client application calls XMapWindow to map a window. If you (usually a win- 
dow manager) had selected SubstructureRedlrectMask on the parent window 
and if the override-redirect attribute of the window is set to False, the XwiN 
server reports a MapRequest event to you and does not map the specified win- 
dow. Thus, this event gives your window manager client the ability to control 
the placement of subwindows. 

The structure for this event type contains: 

typedef struct ( 
int type; 

unsigned long serial; 
Bool sendjBvent; 
Display ^display; 
Window parent; 
Window window; 
} XMapReq^e8tEvMlt; 

The parent member is set to the parent window. The window member is set to 
the window to be mapped. 



/* HapReqfieat */ 

/* # of last request processed by sexrver */ 

/* true if this cane from a SendBvent request V 

/* Display the event was read from */ 



8-46 



Xwin GWS: Xllb - C Language interface 



Event Processing 



ResizeRequest Events 

The XWIN server can report ResizeRequest events to clients wanting informa- 
tion about another client's attempts to change the size of a window. The XwiN 
server generates this event whenever some other client attempts to change the 
size of the specified window by calling XConf igureWindow, XResizeWindow, or 
XMbveReslzeWlndow. 

To receive ResizeRequest events, set the ResizeRedirect bit in the event- 
mask attribute of the window. Any attempts to change the size by other clients 
are then redirected. 

The structure for this event type contains: 

typedef struct { 

int type; /* ResizeRequest */ 

unsigned long serial; /* # of last request processed by server */ 
Bool sendjevent; /* true if this came from a SendEvent request V 

Display ^display; /* Diafplay the event was read from */ 

Window window; 
int width, bei^^t; 
} XResizeHequestEvent; 

The window member is set to the window whose size another client attempted 
to change. The width and height members are set to the inside size of the win- 
dow, excluding the border. 



Colormap State Change Events 

The XwiN server can report ColorxnapNotif y events to clients wanting informa- 
tion about when the colormap changes and when a colormap is installed or 
uninstalled. The XwiN server generates this event type whenever a client appli- 
cation: 

■ Changes the colormap member of the XSetWindowAttributes structure 
by calling XChangeWindowAttributes, XFreeColorinap, or XSetWin- 
dowColorniap 
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■ Installs or uninstalls the coloimap by calling XInstallColonnap or XUn- 
installColonnap 

To receive ColozmapNotify events, set the ColornapChangeMask bit in the 
event-mask attribute of the window. 

The structure for this event type contains: 

tYpedet struct { 



Int type; 


/* 


ColormapNOtify */ 


unsigned long aerial; 


/* 


# of last request processed by server */ 


Bool sendjsvent; 


/* 


true if this came from a SendBvent request V 


Display ^display; 


/* 


Display the event was read from */ 


Window windoir; 






Coloimap coloxnap; 


/* 


colormap or None */ 


Bool new; 






int atate; 


/* 


Colormaplnstalled, ColormapUninstalled */ 



} XColomapBvent; 

The window member is set to the window whose associated colormap is 
changed, installed, or uninstalled. For a colormap that is changed, installed, 
or uninstalled, the colormap member is set to the colormap associated with the 
window. For a colormap that is changed by a call to XFreeColozmap, the 
colormap member is set to None. The new member is set to indicate whether 
the colonnap for the specified window was changed or installed or uninstalled 
and can be True or False. If it is True, the colormap was changed. If it is 
False, the colormap was installed or uninstalled. The state member is always 
set to indicate whetiier the colonnap is installed or uninstalled and can be 
Colonnaplnstalled or ColonnapUninstalled. 



Client Communication Events 

This section discusses: 

■ CllentMessage events 

■ PropertyNotify events 
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■ Select ionClear events 

■ SelectionNotify events 

■ SelectionRequest events 

ClientMessage Events 

The XwiN server generates ClientMessage events only when a client calls the 
function XSendEvent. 

The structure for this event type contains: 

typedef struct { 

int type; /* ClientMessage V 

unsigned long serial;/* # of last request processed by server */ 

Bool sendjevent; /* true if this cane from a SendEvent request */ 

Display Misplay; /* Display the event was read from */ 

Window window; 

Atom nsssage^type; 

int format; 

union { 

char b[20]; 
short s[10]; 
long 1[5]; 

} data; 
} XClientMessageEvent; 

The window member is set to the window to which the event was sent. The 
message_type member is set to an atom that indicates how the data should be 
interpreted by the receiving client The format member is set to 8, 16, or 32 and 
specifies whether the data should be viewed as a list of bytes, shorts, or longs. 
The data member is a union that contains the members b, s, and 1. The b, s, and 
1 members represent data of 20 8-bit values, 10 16-bit values, and 5 32-bit values. 
Particular message types might not make use of all these values. The XwiN 
server places no interpretation on the values in the message_type or data 
members. 
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PropertyNotify Events 

The XWIN server can report PropertyNotify events to clients wanting informa- 
tion about property changes for a specified window. 

To receive PropertyNotify events, set the PropertyChangeMask bit in the 
event-mask attribute of the window. 

The structure for this event type contains: 

typedef struct { 

int type; /* PropertyNotify */ 

unsigned long serial; /* # of last request processed by server */ 
Bool sendjevent; /* true if this came from a SendBvent reqqest */ 

Display *diflplay; /* Display the event was read from V 

Window window; 
Atom atom; 
Time tine; 

int state; /* PropertyNeWValue or PropertyDeleted */ 

} XPropert^vent; 



The window member is set to the window whose associated property was 
changed. The atom member is set to the property's atom and indicates which 
property was changed or desired. The time member is set to the server time 
when the property was changed. The state member is set to indicate whether 
the property was changed to a new value or deleted and can be Proper- 
tyNeWValue or PropertyDelete. The state member is set to Proper- 
tyNewValue when a property of the window is changed using XChangePro- 
perty or XRdtateWindowProperties (even when adding zero-length data 
using XChangeProperty) and when replacing all or part of a property with 
identical data using XChangeProperty or XRotateWindowProperties. The 
state member is set to PropertyDeleted when a property of the window is 
deleted using XDeleteProperty or, if the delete argument is True, XGetWin- 
dowProperty. 
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SelectlonClear Events 



The XWIN server reports SelectlonClear events to the current owner of a 
selection. The XwiN server generates this event type on the window losing 
ownership of the selection to a new owner. This sequence of events could occur 
whenever a client calls XSetSelectlonOwner. 

The structure for this event type contains: 



typ^dtf ttxuot { 

unslgMd long Mrial; 
Bool Mndjtvint; 
Display *dijqplay; 
Window window; 
Aton Mlootion; 
Tim tim; 
} XS«l«otionCl«arSviMiit; 



/* S^UotionClMT */ 

/* # of last Mquait prooossad by wmrvr */ 

/* truo if this aaas fron a S«ndBv«nt rsqusst */ 

/* Diqplay tha avvnt was raad fcom */ 



The window member is set to the window losing ownership of the selection. 
The selection member is set to the selection atom. The time member is set to 
the last change time recorded for the selection. The owner member is the win- 
dow that was specified by the current owner in its XSetSelectionOimer call. 



SelectionRequest Events 

The XwiN server reports SelectionRequest events to the owner of a selection. 
The XwiN server generates this event whenever a client requests a selection 
conversion by calling XConvertSelection and the specified selection is owned 
by a window. 

The structure for this event type contains: 
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typedef struct { 
Int type; 

unsigned long serial; 
Bool sendjsvent; 
Display *diqplay; 
Windoir owner; 
Window requestor; 
Atom selection; 
Atom target; 
Atom property; 
Time time; 
} XSelectionRecpsestEvent; 

The owner member is set to the window owning the selection and is the win- 
dow that was specified by the current owner in its XSetSelectionOwner call. 
The requestor member is set to the window requesting the selection. The selec- 
tion member is set to the atom that names the selection. For example, PRI- 
MARY is used to indicate the primary selection. The target member is set to the 
atom that indicates the type the selection is desired in. The property member 
can be a property name or None. The time member is set to the time and is a 
timestamp or CurrentTiine from the ConvertSelection request. 

The client who owns the selection should do the following: 

■ The owner client should convert the selection based on the atom con- 
tained in the target member. 

■ If a property was specified (that is, the property member is set), the owner 
client should store the result as that property on the requestor window 
and then send a SelectionNotify event to the requestor by calling 
XSendEvent with an empty event-mask; that is, the event should be sent 
to the creator of the requestor window. 

■ If None is specified as the property, the owner client should choose a pro- 
perty name on the requestor window and then send a SelectionNotify 
event giving the actual name. 

■ If the selection cannot be converted as requested, the owner client should 
send a SelectionNotify event with the property set to None. 



/* SelectionReqyest */ 

/* # of last request processed by server */ 

/* true if this cans from a SendBvent request */ 

/* Display the event was read from */ 
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SelectionNotify Events 

This event is generated by the XWIN server in response to a ConvertSelection 
protocol request when there is no owner for the selection. When there is an 
owner, it should be generated by the owner of the selection by using 
XSendEvent. The owner of a selection should send this event to a requestor 
when a selection has been converted and stored as a property or when a selec- 
tion conversion could not be perfonned (which is indicated by setting the pro- 
perty member to None). 

If None is specified as the property in the ConvertSelection protocol request, 
the owner should choose a property name, store the result as tfiat property on 
the requestor window, and then send a SelectionNotify giving that actual 
property name. 

The structure for this event type contains: 

typedef struct { 

int type; /* SelectionNotify */ 

iinsigned long aerial; /* # of last request processed by server */ 
Bool sendjevent; /* true if this came from a SendBvent request V 

Display ^display; /* Display the event was read from */ 

Window requestor; 
Atom selection; 
Atom target; 

Atom property; /* atom or None */ 

Time time; 
} XSelectionEvent; 



The requestor member is set to the window associated with the requestor of the 
selection. The selection member is set to the atom that indicates the selection. 
For example, PRIMARY is used for the primary selection. The target member is 
set to the atom that indicates the converted type. For example, PIXMAP is used 
for a pixmap. The property member is set to the atom that indicates which pro- 
perty the result was stored on. If the conversion failed, the property member is 
set to None. The time member is set to the time the conversion took place and 
can be a timestamp or CurrentTime. 
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There are two ways to select the events you want reported to your client appli- 
cation. One way is to set the event_nriask member of the XSetWinciowAttri- 
butes structure when you call XCreateWindow and XChangeWlndowAttrl- 
butes. Another way is to use XSelect Input. 

XS«l«at Input {display, w, event jnask) 
Display ^display; 
Window w; 
long event jnask; 

display Specifies the connection to the XwiN server. 

w Specifies the window whose events you are interested in. 

event jnask Specifies the event mask. 

The XSelectlnput function requests that the XwiN server report the events 
associated with the specified event mask. Initially, X will not report any of 
these events. Events are reported relative to a window. If a window is not 
interested in a device event, it usually propagates to the closest ancestor that is 
interested, unless the do_notjpropagate mask prohibits it. 

Setting the event-mask attribute of a window overrides any previous call for the 
same window but not for other clients. Multiple clients can select for the same 
events on the same window with the following restrictions: 

■ Multiple clients can select events on the same window because their event 
masks are disjoint. When the XwiN server generates an event, it reports it 
to all interested clients. 

■ Only one client at a time can select CirculateRequest, Conf igureRe- 
quest, or MapRequest events, which are associated with the event mask 
Subst ructureRedirectMask . 

■ Only one client at a time can select a ResizeRequest event, which is 
associated with the event mask ResizeRedirectMask. 

■ Only one client at a time can select a ButtonPress event, which is associ- 
ated with the event mask ButtonPressMask. 

The server reports the event to all interested clients. 

XSelectlnput can generate a BadWindow error. 
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The output buffer is an area used by Xlib to store requests. The functions 
described in this section flush the output buffer if the function would block or 
not return an event. That is, all requests residing in the output buffer that have 
not yet been sent are transmitted to the XwiN server. These functions differ in 
the additional tasks they might perform. 

To flush the output buffer, use XFlush. 

IXEluatii display) 
Display ^display; 

display Specifies the connection to the XwiN server. 

The XFlush function flushes the output buffer. Most client applications need 
not use this function because the output buffer is automatically flushed as 
needed by calls to XPending, XNext Event, and XWindowEvent. Events gen- 
erated by the server may be enqueued into the library's event queue. 

To flush the output buffer and then wait until all requests have been processed, 
use XSync. 

XSync {display, discard) 
Display *display; 
Bool discard; 

display Specifies the connection to the XwiN server. 

discard Specifies a Boolean value that indicates whether XSync discards 

all events on the event queue. 

The XSync function flushes the output buffer and then waits until all requests 
have been received and processed by the XwiN server. Any errors generated 
must be handled by the error handler. For each error event received by Xlib, 
XSync calls the client application's error handling routine (see "Using the 
Default Error Handlers" in this chapter). Any events generated by the server 
are enqueued into the library's event queue. 

Finally, if you passed False, XSync does not discard the events in the queue. If 
you passed True, XSync discards all events in the queue, including those events 
that were on the queue before XSync was called. Client applications seldom 
need to call XSync. 
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Xlib maintains an event queue. However, the operating system also may be 
buffering data in its network connection that is not yet read into the event 
queue. 

To check the number of events in the event queue, use XEventsQueued. 

int TEvw^taQijmjBd (display, mode) 
Display *display; 
int mode; 

display Specifies the connection to the XwiN server. 

mode Specifies the mode. You can pass QueuedAlready, QueuedAf- 

terFlush, or QueuedAfterReading. 

If mode is QueuedAlready, XEventsQueued returns the number of events 
already in the event queue (and never performs a system call). If mode is 
QueuedAfterFlush, XEventsQueued returns the number of events already in 
the queue if the number is nonzero. If there are no events in the queue, 
XEventsQueued flushes the output buffer, attempts to read more events out of 
the application's connection, and returns the number read. If mode is 
QueuedAfterReading, XEventsQueued returns the nuniber of events already in 
the queue if the number is nonzero. If there are no events in the queue, 
XEventsQueued attempts to read more events out of the application's connec- 
tion without flushing the output buffer and returns the number read. 

XEventsQueued always returns immediately without I/O if there are events 
already in the queue. XEventsQueued with mode QueuedAfterFlush is identi- 
cal in behavior to XPending. XEventsQueued with mode QueuedAlready is 
identical to the XQLength function. 

To return the number of events that are pending, use XPending. 

int XBexidixMS (display) 
Display ^display; 

display Specifies the connection to the XwiN server. 

The XPending function returns the number of events that have been received 
from the XwiN server but have not been removed from the event queue. XPend- 
ing is identical to XEventsQueued with the mode QueuedAfterFlush specified. 
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Xlib provides functions that let you manipulate the event queue. The next three 
sections discuss how to: 

■ Obtain events, in order, and remove them from the queue 

■ Peek at events in the queue without removing fhem 

■ Obtain events that match the event mask or the arbitrary predicate pro- 
cedures that you provide 



Returning tlie Next Event 

To get the next event and remove it from the queue, use XNextEvent. 

XNextEvent {display, event jretum) 
Display *display; 
XEvent *eventjetum; 

display Specifies the connection to the XWIN server. 

event jetum Returns the next event in the queue. 

The XNextEvent function copies the first event from the event queue into the 
specified XEvent structure and then removes it from the queue. If the event 
queue is empty, XNextEvent flushes the output buffer and blocks until an event 
is received. 

To peek at the event queue, use XPeekEvent. 

XPeekEvent {display, event jretum) 
Display ^display) 
XEvent *eventjetum; 

display Specifies the connection to the XwiN server. 

event jetum Returns a copy of the matched event's associated structure. 

The XPeekEvent function returns the first event from the event queue, but it 
does not remove the event from the queue. If the queue is empty, XPeekEvent 
flushes the output buffer and blocks until an event is received. It then copies 
the event into the client-supplied XEvent structure without removing it from 
the event queue. 
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Selecting Events Using a Predicate Procedure 

Each of the functions discussed in this section requires you to pass a predicate 
procedure that determines if an event matches what you want. Your predicate 
procedure must decide only if the event is useful and must not call Xlib func- 
tions. In particular, a predicate is called from inside the event routine, which 
must lock data structures so that the event queue is consistent in a multi- 
threaded environment. 

The predicate procedure and its associated arguments are: 

Bool {*jnredicaU){display, event, org) 
Display ^display; 
XEvent *ez?ent; 
char *earg; 

display Specifies the connection to the XwiN server. 

event Specifies a pointer to the XEvent structure. 

arg Specifies the argument passed in from the Xlf Event, 

XChecklfEvent, or XPeeklfEvent function. 

The predicate procedure is called once for each event in the queue until it finds 
a match. After finding a match, the predicate procedure must return True. If it 
did not find a match, it must return False. 

To check the event queue for a matching event and, if found, remove the event 
from the queue, use Xlf Event. 

XlfEvent {dispUof, event jetum, predicate, arg) 
Display ^display; 
XEvent *eventjretum; 
Bool (*predicate)0; 
char *arg; 

display Specifies the connection to the XwiN server. 

event return Returns the matched event's associated structure. 
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predicate Specifies the procedure that is to be called to determine if the 

next event in the queue matches what you want. 

arg Specifies the user-supplied argument that will be passed to the 

predicate procedure. 

The XlfEvent function completes only when the specified predicate procedure 
returns True for an event, which indicates an event in the queue matches. 
XlfEvent flushes the output buffer if it blocks waiting for additional events. 
XlfEvent removes the matching event from the queue and copies the structure 
into the client-supplied XEvent structure. 

To check the event queue for a matching event without blocking, use 
XChecklfEvent . 

Bool XChecklfEvent {display, eoentjetum, predicate, arg) 
Display ^display; 
XEvent *event_retum; 
Bool {*predicaU)0; 
char *arg; 

display Specifies the connection to the XwiN server. 

event jetum Returns a copy of the matched event's associated structure. 

predicate Specifies the procedure that is to be called to determine if the 

next event in the queue matches what you want. 

arg Specifies the user-supplied argument that will be passed to the 

predicate procedure. 

When the predicate procedure finds a match, XChecklfEvent copies the 
matched event into tihe client-supplied XEvent structure and retums True. 
(This event is removed from the queue.) If the predicate procedure finds no 
match, XChecklfEvent retums False, and the output buffer will have been 
flushed. All earlier events stored in the queue are not discarded. 

To check the event queue for a matching event without removing the event 
from the queue, use XPeeklfEvent. 
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XPaaklfBvttnt {display, event jretum, ftredicate, arg) 
Display ^display; 
XEvent *eoentjretum; 
Bool (*predkaU)0; 
char *arg; 

display Specifies the connection to the XwiN server. 

event jetum Returns a copy of the matched event's associated structure. 

predicate Specifies the procedure that is to be called to determine if the 
next event in the queue matches what you want. 

arg Specifies the user-supplied argument that will be passed to the 

predicate procedure. 

The XPeeklf Event function returns only when the specified predicate pro- 
cedure returns True for an event. After the predicate procedure finds a match, 
XPeeklfEvent copies the matched event into the dient-supplied XEvent struc- 
ture without removing the event from the queue. XPeeklfEvent flushes the 
output buffer if it blocks waiting for additional events. 



Selecting Events Using a Window or Event Masic 

The functions discussed in this section let you select events by window or event 
types, allowing you to process events out of order. 

To remove the next event that matches both a window and an event mask, use 
XWindowEvent. 

3C9rindoiiBvient {display, w, event jnask, event jretum) 
Display ^display; 
Window w; 
long event jnask; 
XEvent *eoentjetum; 

display Specifies the connection to the XwiN server. 
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w Specifies the window whose events you are interested in. 

event jnask Specifies the event n\ask. 

event jetum Returns the matched event's associated structure. 

The XWindowEvent function searches the event queue for an event that matches 
both the specified window and event mask. When it finds a match, XWin- 
dowEvent removes that event from the queue and copies it into the specified 
XEvent structure. The other events stored in the queue are not discarded. If a 
matching event is not in the queue, XWindowEvent flushes the output buffer and 
blocks until one is received. 

To remove the next event that matches both a window and an event mask (if 
any), use XChedcWindowEvent. This function is similar to XWindowEvent except 
that it never blocks and it returns a Bool indicating if the event was returned. 

Bool XChAckWindoMBvent {display, w, event jnask, event jetum) 
Display *display; 
Window w; 
long event jnask; 
XEvent *eventjetum) 

display Specifies the connection to the XwiN server. 

w Specifies the window whose events you are interested in. 

event jnask Specifies the event mask. 

event jeturn Returns the matched event's associated structure. 

The XCheckWindowEvent function searches the event queue and then the events 
available on the server connection for the first event that matches the specified 
window and event mask. If it finds a match, XCheckWindowEvent removes that 
event, copies it into the specified XEvent structure, and returns True. The other 
events stored in the queue are not discarded. If the event you requested is not 
available, XCheckWindowEvent returns False, and the output buffer will have 
been flushed. 

To remove the next event that matches an event mask, use XMaskEvent. 
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XHMkBvmt (display, event jnask, event jretum) 
Display ^display; 
long euentjmsk; 
XEvent *eventjetum; 

display Specifies the connection to the XwiN server. 

event jna$k Specifies the event mask. 

event jetum Returns the matched event's associated structure. 

The XMaskEvent function searches the event queue for the events associated 
with the specified mask. When it finds a match, XMaskEvent removes that 
event and copies it into the specified XEvent structure. The other events stored 
in the queue are not discarded. If the event you requested is not in the queue, 
XMaskEvent flushes the output buffer and blocks until one is received. 

To return and remove the next event that matches an event mask (if any), use 
XCheckMaskEvent. This function is similar to XMaskEvent except that it never 
blocks and it returns a Bool indicating if the event was returned. 

Bool XCbec]cMa8kE¥Mit(t/i5p%, ei^t^mosii:, £t^f_reh<rn) 
Display ^display; 
long event jnask; 
XEvent *eventjetum; 

display Specifies the connection to the XwiN server. 

event jnask Specifies the event mask. 

event jetum Returns the matched event's associated structure. 

The XCheckMaskEvent function searches the event queue and then any events 
available on the server connection for the first event that matches the specified 
mask. If it finds a match, XCheckMaskEvent removes that event, copies it into 
the specified XEvent structure, and returns True. The other events stored in 
the queue are not discarded. If the event you requested is not available, 
XCheckMaskEvent returns False, and the output buffer will have been flushed. 

To return and remove the next event in the queue that matches an event type, 
use XCheckTypedEvent. 
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Bool XCbackTypedBvent {display, euentjype, event jetum) 
Display ^display; 
int event Jype; 
XEvent *eventj^tum; 



display 
event Jype 



Specifies the connection to the XwiN server. 
Specifies the event type to be compared. 



event jretum Returns the matched event's associated structure. 

The XCheckTypedEvent function searches the event queue and then any events 
available on the server connection for the first event that matches the specified 
type. If it finds a match, XCheckTypedEvent removes that event, copies it into 
the specified XEvent structure, and returns True. The other events in the queue 
are not discarded. If the event is not available, XCheckTypedEvent returns 
False, and the output buffer will have been flushed. 

To return and remove the next event in the queue that matches an event \y]^ 
and a window, use XCheckTypedWindowEvent. 

Bool XChackTypedWindoi^vttnt {display, w, event Jype, event jretum) 
Display ^display; 
Window w; 
int event Jype; 
XEvent *event_retum; 

display Specifies the connection to the XwiN server. 

w Specifies the window. 

event Jype Specifies the event type to be compared. 

event jetum Returns the matched event's associated structure. 

The XCheckTypedWindowEvent function searches the event queue and then any 
events available on the server connection for the first event ttiat matches the 
specified type and window. If it finds a match, XCheckTypedWindowEvent 
removes the event from the quejie, copies it into the specified XEvent structure, 
and returns True. The other events in the queue are not discarded. If the event 
is not available, XCheckTypedWindowEvent returns False, and the output 
buffer will have been flushed. 
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To push an event back into the event queue, use XPutBackEvent. 

XPutBackEvant (display, event) 
Display ^display; 
XEvent *event; 

display Specifies the connection to the XwiN server. 

event Specifies a pointer to the event. 

The XPutBackEvent function pushes an event back onto the head of the 
display's event queue by cop)dng the event into the queue. This can be useful if 
you read an event and then decide that you would rather deal with it later. 
There is no limit to the number of times in succession that you can call 
XPutBackEvent . 



8-64 



Xwin GWS: Xllb ~ C Language Interface 



Sending Events to Other Applications 



To send an event to a specified window, use XSendEvent. This function is often 
used in selection processing. For example, the owner of a selection should use 
XSendEvent to send a SelectionNotify event to a requestor when a selection 
has been converted and stored as a property. 

status XSendEvent {display, w, propagate, event jmsk, event jend) 



Display ^display; 
Window w; 
Bool propagate; 
long event jnask; 
XEvent *eventjend; 



The XSendEvent function identifies the destination window, determines which 
clients should receive the specified events, and ignores any active grabs. This 
function requires you to pass an event mask. For a discussion of the valid event 
mask names, see "Event Masks" in this chapter. This function uses the w argu- 
ment to identify the destination window as follows: 

■ If w is PointerWindow, the destination window is the window that con- 
tains the pointer. 

■ If w is InputFocus and if the focus window contains the pointer, the des- 
tination window is the window that contains the pointer; otherwise, the 
destination window is the focus window. 

To determine which clients should receive the specified events, XSendEvent 
uses the propagate argument as follows: 

■ If event_mask is the empty set, the event is sent to the client that created 
the destination window. If that client no longer exists, no event is sent 
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Specifies the connection to the XwiN server. 

Specifies the window the event is to be sent to, PointerWindow, 
or InputFocus. 

Specifies a Boolean value. 

Specifies the event mask. 

Specifies a pointer to the event that is to be sent 



w 



propagate 
event mask 



event send 



Sending Events to Other Applications 



■ If propagate is False, the event is sent to every client selecting on desti- 
nation any of the event types in the event_mask argument. 

■ If propagate is True and no clients have selected on destination any of the 
event types in event-mask, the destination is replaced with the closest 
ancestor of destination for which some client has selected a type in event- 
mask and for which no intervening window has that type in its do-not- 
propagate-mask. If no such window exists or if the window is an ancestor 
of the focus window and Ir^utFocus was originally specified as the des- 
tination, the event is not sent to any clients. Otherwise, the event is 
reported to every client selecting on the final destination any of the types 
specified in event_mask. 

The event in the XEvent structure must be one of the core events or one of the 
events defined by an extension (or a BadValue error results) so that the XwiN 
server can correctly byte-swap the contents as necessary. The contents of the 
event are otherwise unaltered and unchecked by the XwiN server except to force 
send_event to True in the forwarded event and to set the serial number in the 
event correctly. 

XSendEvent returns zero if the conversion to wire protocol format failed and 
returns nonzero otherwise. 

XSendEvent can generate BadValue and BadWindow errors. 
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Some XwiN server implementations will maintain a more complete history of 
pointer motion than is reported by event notification. The pointer position at 
each pointer hardware interrupt may be stored in a buffer for later retrieval. 
This buffer is called the motion history buffer. For example, a few applications, 
such as paint programs, want to have a precise history of where the pointer 
traveled. However, this historical information is highly excessive for most appli- 
cations. 

To determine the size of the motion buffer, use XDisplayMotionBuf ferSize. 

unsigned long XDioplayMotionBufferSize (<^is;7l^y) 
Display *disp1ay; 

display Specifies the connection to the XwiN server. 

The server may retain the recent history of the pointer motion and do so to a 
finer granularity than is reported by MotionNotif y events. 
The XGetiMotionEvents function makes this history available. 

To get the motion history for a specified window and time, 
use XGetMotionEvents. 

XTimCooxd *XGetlfotionBvent8 (<{isp/ay, w, start, stop, neventsjetum) 
Display ^display; 
Window w; 
Time start, stop; 
int *neventsjretum; 

display Specifies the connection to the XwiN server. 

w Specifies the window. 

start 

stop Specify the time interval in which the events are returned from 

the motion history buffer. You can pass a timestamp or 
CurrentTime. 

neventsjreturn 

Returns the number of events from the motion history buffer. 
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The XGetiMotionEvents function returns all events in the motion histoiy buffer 
that fall between the specified start and stop times, inclusive, and that have 
coordinates that lie within the specified window (including its borders) at its 
present placement. If the start time is later than the stop time or if the start 
time is in the future, no events are returned. If the stop time is in the future, it 
is equivalent to specifying CurrentTiroe. The return type for this function is a 
structure defined as follows: 

t^npedef struct { 

Tine time; 

short X, y; 
) XlimeCoord; 

The time member is set to the time, in milliseconds. The x and y members are 
set to the coordinates of the pointer and are reported relative to the origin of the 
specified window. To free the data returned from this call, use XFree. 

XGetiMotionEvents can generate a BadWindow error. 
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Xlib provides functions that you can use to enable or disable synchronization 
and to use the default error handlers. 



Enabling or Disabling Synchronization 

When debugging X applications, it often is very convenient to require Xlib to 
behave synchronously so that errors are reported as they occur. The following 
function lets you disable or enable synchronous behavior. Note that graphics 
may occur 30 or more times more slowly when synchronization is enabled. On 
UNIX-based systems, there is also a global variable _Xdebug that, if set to 
nonzero before starting a program under a debugger, will force synchronous 
library behavior. 

After completing their work, all Xlib functions that generate protocol requests 
call what is known as an after function. XSetJVf terFunction sets which func- 
tion is to be called. 

int (*XSetAfteiStinction {display, procedure))0 
Display ^display; 
int (*proceduf€)Oi 

display Specifies the connection to the Xwnsr server. 

procedure Specifies the function to be called after an Xlib function that 
generates a protocol request completes its work. 

The specified procedure is called with only a display pointer. XSetAf terFunc- 
tion returns ttie previous after function. 

To enable or disable synchronization, use XSynchronize. 

int (*XSynchronize((}is^Zay, oifojp}0 
Display ^display; 
Bool onoff; 

display Specifies the connection to the XwiN server. 
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onoff Specifies a Boolean value that indicates whether to enable or dis- 

able synchronization. 

The XSynchronlze function returns the previous after function. If onoff is 
True, XSynchronlze turns on synchronous behavior. If onoff is False, XSyn- 
chronlze turns off synchronous behavior. 

Using the Default Error Handlers 

There are two default error handlers in Xlib: one to handle typically fatal condi- 
tions (for example, the connection to a display server dying because a machine 
crashed) and one to handle error events from the XwiN server. These error 
handlers can be changed to user-supplied routines if you prefer your own error 
handling and can be changed as often as you like. If either function is passed a 
NULL pointer, it will reinvoke the default handler. The action of the default 
handlers is to print an explanatory message and exit. 

To set the error handler, use XSetErrorHandler. 

XSetErrorHandler {handler) 

int (♦/wwiferXDisplay XEixorEvent ♦) 

handler Specifies the program's supplied error handler. 

Xlib generally calls the program's supplied error handler whenever an error is 
received. It is not called on BadName errors from OpenFont, LookupColor, or 
AllocNamedColor protocol requests or on BadFont errors from a QueryFont 
protocol request. TTiese errors generally are reflected back to the program 
through the procedural interface. Because this condition is not assumed to be 
fatal, it is acceptable for your error handler to return. However, the error 
handler should not call any functions (directly or indirectly) on the display that 
will generate protocol requests or that will look for input events. 

The XErrorEvent structure contains: 
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typedef struct { 
int typ«; 
Display "^display; 
unaigned long aerial; 
unsigned char errorjcxxie; 



/* Display the event was read from */ 
/* serial nunter of failed request */ 
/* error code of failed request */ 



unsigned char reqoestjcsode; /* Hajor op-code of failed request */ 



> XBrrorBvent; 

The serial member is the number of requests, starting from one, sent over the 
network connection since it was opened. It is the number that was the value of 
NextRequest immediately before the failing call was made. The request_code 
member is a protocol request of the procedure that failed, as defined in 
< Xll/Xproto.h >. The following error codes can be returned by the functions 
described in this chapter: 



Error Code Description 



BadAccess A client attempts to grab a key /button combi- 



nation already grabbed by another client. 

A client attempts to free a colormap entry that 
it had not already allocated. 

A client attempts to store into a read-only or 
unallocated colormap entry. 

A client attempts to modify the access control 
list from other than the local (or otherwise 
authorized) host. 

A client attempts to select an event type that 
another client has already selected. 



unsigned char minor jcx>de; 
XID resouroeid; 



/* Minor op-code of failed request */ 
/* resource id */ 



BadAlloc 



The server fails to allocate the requested 
resource. Note that the explicit listing of 
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Description 



BadAlloc errors in requests only covers alloca- 
tion errors at a very coarse level and is not 
intended to (nor can it in practice hope to) 
cover all cases of a server running out of allo- 
cation space in the middle of service. The 
semantics when a server runs out of allocation 
space are left unspecified, but a server may 
generate a BadAlloc error on any request for 
this reason, and clients should be prepared to 
receive such errors and handle or discard them. 



BadAtom 

BadColor 

BadCursor 

BadDrawable 

BadFont 

BadGC 

BadlDChoice 



Badlitplenien- 
tation 



A value for an atom argument does not name a 
defined atom. 

A value for a colormap argument does not 
name a defined colormap. 

A value for a cursor argument does not name a 
defined cursor. 

A value for a drawable argument does not 
name a defined window or pixmap. 

A value for a font argument does not name a 
defined font (or, in some cases, GContext). 

A value for a GContext argument does not 
name a defined GContext. 

The value chosen for a resource identifier 
either is not included in the range assigned to 
the client or is already in use. Under normal 
circumstances, this cannot occur and should be 
considered a server or Xlib error. 

The server does not implement some aspect of 
the request A server that generates this error 
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Description 



for a core request is deficient. As such, this 
error is not listed for any of the requests, but 
clients should be prepared to receive such 
errors and handle or discard them. 

BadLength The length of a request is shorter or longer 

than that required to contain the arguments. 
This is an internal Xlib or server error. 

The length of a request exceeds the maximum 
length accepted by the server. 

BadMatch In a graphics request, the root and depth of the 

graphics context does not match that of the 
drawable. 

An inputOnly window is used as a drawable. 

Some argument or pair of arguments has the 
correct type and range, but it fails to match in 
some other way required by the request. 

An InputOnly window lacks this attribute. 

BadNaine A font or color of the specified name does not 

exist. 

BadPixmap A value for a pixmap argument does not name 

a defined pixmap. 

BadRequest The major or nunor opcode does not specify a 
valid request. This usually is an Xlib or server 
error. 

BadValue Some numeric value falls outside of the range 

of values accepted by the request. Unless a 
specific range is specified for an argument, the 
full range defined by the argument's type is 
accepted. Any argument defined as a set of 
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Error Code Description 



alternatives t3^ically can generate this error 
(due to the encoding). 

BadWindow A value for a window argument does not 

name a defined window. 



The BadAtom, BadColor, BadCursor, BadDrawable, BadFont, BadGC, Bad- 
NOTE Pixmap, and BadWdLndow errors are also used when the argument type Is 
extended by a set of fixed alternatives. 



To obtain textual descriptions of the specified error code, use XGetErrorText. 

XGetErrorText { display, code, buffer jretum, length) 
Display *displaj/; 
int code; 

char *huffer jretum) 
int length; 

display Specifies the connection to the XwiN server. 

code Specifies the error code for which you want to obtain a descrip- 

tion. 

buffer jetum Returns the error description. 
length Specifies the size of the buffer. 

The TOetErrorText function copies a null-terminated string describing the 
specified error code into the specified buffer. It is recommended that you use 
this function to obtain an error description because extensions to Xlib may 
define their own error codes and error strings. 

To obtain error messages from the error database, use XGetErrorData- 
baseText. 
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XGetErrorDatabaseText {display, name, message, default jtring, buffer jetum, length) 
Display ^display; 
char *name, *message; 
char *default_string; 
char *bufferjretum; 
int lengih; 



display 
name 
message 
defaultjtring 

buffer jetum 
length 



Specifies the connection to the XwiN server. 

Specifies the name of the application. 

Specifies the of the error message. 

Specifies the default error message if none is found in the data- 
base. 

Returns the error description. 
Specifies the size of the buffer. 



The XGetErrorDatabaseText function returns a message (or the default mes- 
sage) from the error message database. Xlib uses this function internally to look 
up its error messages. On a UNIX-based system, the error message database is 
/usr/X/lib/XErrorDB . 

The name argument should generally be the name of your application. The 
message argument should indicate which type of error message you want. Xlib 
uses three predefined message types to report errors (uppercase and lowercase 
matter): 

XProtoError The protocol error number is used as a string for the message 
argument. 

XlibMessage These are the message strings that are used internally by the 
library. 

XRequest The major request protocol number is used for the message 
argument. If no string is found in the error database, the 
default_string is returned to the buffer argument. 

To report an error to the user when the requested display does not exist, use 
XDispla^anie. 
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char *XDispla.^Uaim {string) 
char '^string; 

string Specifies the character string. 

The XDisplayNaine function returns the name of the display that XOpenDisplay 
would attempt to use. If a NULL string is specified, XDisplayNaine looks in the 
environment for the display and returns the display name that XOpenDisplay 
would attempt to use. This makes it easier to report to the user precisely which 
display the program attempted to open when the initial connection attempt 
failed. 

To handle fatal I/O errors, use XSetlOErrorHandler. 

XSetlOBrrozHandler (handler) 
int (♦/wmiter) (Display ♦); 

handler Specifies the program's supplied error handler. 

The XSetlOErrorHandler sets the fatal I/O error handler. Xlib calls the 
program's supplied error handler if any sort of system call error occurs (for 
example, the connection to the server was lost). This is assumed to be a fatal 
condition, and the called routine should not return. If the I/O error handler 
does return, the client process exits. 
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Introduction 



There are a number of predefined properties for information commonly associ- 
ated with windows. The atoms for these predefined properties can be found in 
< Xll/Xatom.h >, where the prefix XA_ is added to each atom name. 

Xlib provides functions that you can use to perform operations on predefined 
properties. This chapter discusses how to: 

■ Communicate with window managers 

■ Manipulate standard colormaps 
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Communicating with Window Managers 



This section discusses a set of properties and functions that are necessary for 
clients to communicate effectively with window managers. Some of these pro- 
perties have complex structures. Because all the data in a single property on the 
server has to be of the same format (8-bit, 16-bit, or 32-bit) and because the C 
structures representing property types cannot be guaranteed to be uniform in 
the same way. Set and Get functions are provided for properties with complex 
structures. 

These functions define but do not enforce minimal policy among window 
managers. Writers of window managers are urged to use the information in 
these properties rather than invent their own properties and types. A window 
manager writer, however, can define additional properties beyond this least 
common denominator. 

In addition to Set and Get functions for individual properties, Xlib includes one 
function, XSetStandardProperties, that sets all or portions of several proper- 
ties. Applications are encouraged to provide the window manager more infor- 
mation than is possible with XSetStandardProperties. To do so, they should 
call the Set functions for the additional or specific properties that they need. 

To work well with most window managers, every application should specify the 
following information: 

■ Name of the application 

■ Name to be used in the icon 

■ Command used to invoke the application 

■ Size and window manager hints 

Xlib does not set defaults for the properties described in this section. Thus, the 
default behavior is determined by the window manager and may be based on 
the presence or absence of certain properties. All the properties are considered 
to be hints to a window manager. When implementing window management 
policy, a window manager determines what to do with this information and can 
ignore it. 
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The supplied properties are: 



Name 


Type 


Format 


Description 


WM_NAME 


snoNG 


8 


Name of the application. 


WMJCON_NAME 


STRING 


8 


Name to be used in icon. 


WM^NORMAL^HINTS 




32 


Size hints for a window in its normal 
state. The C type of this property is 
XSlzaHints. 


WM_ZOOM_HINTS 


WMJIZE^MNTS 


32 


Size hints for a zoomed window. The 
C type of this property is XSizeHints. 


WM_HINTS 


WMJHINTS 


32 


Additional hints set by client for use by 
the window manager. The C type of 
this property is XWMEIints. 


WM__COMMAND 


STRING 


Q 
O 


The command and arguments^ 
separated by ASQI nulls, used to 
invoke the application. 


WMJCONJIZE 


WMJCON^SIZE 


32 


The window manager may set this pro- 
perty on the root window to specify the 
icon sizes it supports. The C type of 
this property is XloonSize. 


WM^CLASS 


STRING 


32 


Set by application programs to allow 
window and session managers to 
obtain the application's resources from 
the resource database. 


WM_TRANSIEOTJOR 


WINDOW 


32 


Set by application programs to indicate 
to the v^dow manager that a transient 
top-level window, such as a dialog box, 
is not really a normal application win- 
dow. 
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The atom names stored in < Xll/Xatom.h > are named XA_PROPERTY_NAME. 

Xlib provides functions that you can use to set and get predefined properties. 
Note that calling the Set function for a property with complex structure 
redefines all members in that property, even though only some of those 
members may have a specified new value. Simple properties for which Xlib 
does not provide a Set or Get function can be set by using XChangeProperty, 
and their values can be retrieved using XGetWindowPrqperty. The remainder 
of this section discusses how to: 

■ Set standard properties 

■ Set and get the name of a window 

■ Set and get the icon name of a window 

■ Set the command and arguments of the application 

■ Set and get window manager hints 

■ Set and get window size hints 

■ Set and get icon size hints 

■ Set and get the class of a window 

■ Set and get the transient property for a window 



Setting Standard Properties 

To specify a minimum set of properties describing the "quickie" application, use 
XSetStandardProperties. This function sets all or portions of the 
WM^NAME, WM ICON^NAME, WM_.HINTS, WM^COMMAND, and 
WM^^NORM AL^MNTS properties. 
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XSetStandardProperties ((^isp/ay, w, window jiame, iamjtame, iconjnxmap, argv, argc, hints) 
Display ^display; 
Window w; 
char *window_mme; 
char *iam mme; 
Bxmap iconjnxmap; 
char **argv; 
int argc; 

XSizeHints *hints; 



display Specifies the connection to the XwiN server. 

w Specifies the window. 

tmndowjiame Specifies the window name, which should be a null-terminated 
string. 

iconjiame Specifies the icon name, which should be a null-terminated 
string. 

iconjnxmap Specifies the bitmap that is to be used for the icon or None. 
argo Specifies the application's argument list. 

argc Specifies the number of arguments. 

hints Specifies a pointer to the size hints for the window in its normal 

state. 



The XSetStandardProperties function provides a means by which simple 
applications set the most essential properties with a single call. XSetStan- 
dardProperties should be used to give a window manager some information 
about your program's preferences. It should not be used by applications that 
need to communicate more information than is possible with XSetStandardPro- 
perties. (Typically, argv is the argv array of your main program.) 

XSetStandardProperties can generate BadAlloc and BadWindow errors. 
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Setting and Getting Window Names 

Xlib provides functions that you can use to set and read the name of a window. 
These functions set and read the WM_NAME property. 

To assign a name to a window, use XStoreNaine. 

XStoreName (display, w, vmdowjiame) 
Display ^display; 
Window w; 
char *windowjiame; 

display Specifies the connection to the XwiN server. 

w Specifies the window. 

window jiame Specifies the window name, which should be a null-terminated 
string. 

The XStoreNaine function assigns the name passed to window_name to the 
specified window. A window manager can display the window name in some 
prominent place, such as the title bar, to allow users to identify windows easily. 
Some window managers may display a window's name in the window's icon, 
although they are encouraged to use the window's icon name if one is provided 
by the application. 

XStoreNaine can generate BadAlloc and BadWindow errors. 

To get the name of a window, use XFetchNaine. 

status XFetchNams {display, w, window jumtejetum) 
Display *display; 
Window w; 

char "^wirtdawjuanejeturn; 

Specifies the connection to the XwiN server. 
Specifies the window. 
mmejretum 

Returns a pointer to the window name, which is a null- 
terminated string. 
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The XFetchNanie function returns the name of the specified window. If it 
succeeds, it returns nonzero; otherwise, if no name has been set for the window, 
it returns zero. If the WM_NAME property has not been set for this window, 
XFetchName sets window_name_retum to NULL. When finished with it, a 
client must free the window name string using XFree. 

XFetchName can generate a BadWindow error. 

Setting and Getting Icon Names 

Xlib provides functions that you can use to set and read the name to be 
displayed in a window's icon. These functions set and read the 
WM JCON^NAME property. 

To set the name to be displayed in a window's icon, use XSetlconNarae. 

XSetloonName {display, w, iamjiame) 
Display *display; 
Window w; 
char *iamjiame; 

display Specifies the connection to the XwiN server. 

XV Specifies the window. 

iconjume Specifies the icon name, which should be a null-terminated 
string. 

XSetlconNarae can generate BadAlloc and BadWindow errors. 

To get the name a window wants displayed in its icon, use XGetlconNarae. 

status XGetlcsohNane (itsfilay, w, iconjiamejretum) 
Display *display; 
Window w; 

char **icon jmme_retum ; 

display Specifies the connection to the XwiN server. 
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w Specifies the window. 

iconjiamejeturn 

Returns a pointer to the window's icx>n name, which is a null- 
terminated string. 

The XGetlconName function returns the name to be displayed in the specified 
window's icon. If it succeeds, it returns nonzero; otherwise, if no icon name has 
been set for the window, it returns zero. If you never assigned a name to the 
window, XGetlconNaine sets icon_name_retum to NULL. When finished with 
it, a client must free the icon name string using XFree. 

XGetlcx>nName can generate a BadWindow error. 

Setting the Command 

To set the command property, use XSetCoinraand. This function sets the 
WM__COMMAND property. 

YS^tCoaoiaiid {display, w, argu, argc) 
Display ^display; 
Window w; 
char **argv; 
int argc; 



display Specifies the connection to the XwiN server. 

w Specifies the window. 

argv Specifies the application's argument list. 

argc Specifies the number of arguments. 



The XSetCamroand function sets the command and arguments used to invoke the 
application. (Typically, argv is the argv array of your main program.) 

XSetCcsnsnand can generate BadAlloc and BadWindow errors. 
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Setting and Getting Window Manager Hints 

The functions discussed in this section set and read the WM HINTS 
property and use the flags and the XWMHints structure, as defined in the 
< Xll/Xutil.h > header file: 

/* Window manager hints mask bits */ 



#defme 


InputHint 


(1L«0) 


#define 


StateHint 


(IL « 1) 


#defme 


IconP ixmi^int 


(IL « 2) 


#define 


IconWindonHint 


(1L«3) 


#de£ine 


Ic^ositionHint 


(1L«4) 


#defme 


IconMaskHint 


(IL « 5) 


#de£ine 


WindoiiiGroi^Hint 


(IL « 6) 


#define 


AllHints 


(InputHint | StateHint | tonBxmapHint | 



IconWindowHint | IconPositionHint | 
IconMaskHint | WindowGroupHint) 



/* Values */ 



typedef struct { 
long flags ; 
Bool ii^ut; 

int initial^state; 
Pixroap icon^pixnu^; 
Window ioonjvindow; 
int ioonjc, ioonjf; 
Pixmap iconjnask; 
XID windowjgroup; 
/* this structure may be extended in the future */ 
> XBMIints; 



/* marks which fields in this structure are defined */ 
/* does this s^lication rely on the window manager to 
get keyboard input? */ 
/* see below */ 

/* pixmap to be used as icon */ 
/* window to be used as icon V 
/* initial position of icon */ 
/* pixmap to be used as mask for iconjpixmap */ 
/* id of related window groiqp */ 



The input member is used to communicate to the window manager the input 
focus model used by the application. Applications that expect input but never 
explicitly set focus to any of their subwindows (that is, use the push model of 
focus management), such as XlO-style applications that use real-estate driven 
focus, should set this member to True. Similarly, applications that set input 
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focus to their subwindows only when it is given to their top-level window by a 
window manager should also set this member to True. Applications that 
manage their own input focus by explicitly setting focus to one of their subwin- 
dows whenever they want keyboard input (that is, use the pull model of focus 
management) should set this member to False. Applications that never expect 
any keyboard input also should set this member to False. 

Pull model window managers should make it possible for push model applica- 
tions to get input by setting input focus to the top-level windows of applications 
whose input member is True. Push model window managers should make sure 
that pull model applications do not break them by resetting input focus to Poin- 
terRoot when it is appropriate (for example, whenever an application whose 
input member is False sets input focus to one of its subwindows). 

The definitions for the initial_state flag are: 

#define DontCareState 0 /♦ don't know or care */ 

#define NonnalState 1 I* most applications start this way *l 

#define ZoomState 2 I* application wants to start zoomed *l 

#de£ine IcionicState 3 ^ application wants to start as an icon 

V 

#de£ine InactiveState 4 I* application believes it is seldom 

used; 

some wm's may put it on inactive 
menu */ 

The icon_mask specifies which pixels of the icon_pixmap should be used as the 
icon. This allows for nonrectangular icons. Both the icon_pixmap and 
icon_mask must be bitmaps. The icon window lets an application provide a 
window for use as an icon for window managers that support such use. The 
window_group lets you specify that this vrindow belongs to a group of other 
windows. For example, if a single application manipulates multiple top-level 
windows, this allows you to provide enough information that a window 
manager can iconify ail of the windows rather than just the one window. 

To set the window manager hints for a window, use XSetWMHints. 
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XSetVMlnts (display, w, umhints) 
Display ^display; 
Window w; 
XWMHints *iimikints; 



display 



Specifies the connection to the XwiN server. 
Specifies the window. 

Specifies a pointer to the window manager hints. 



XV 



wmhinis 



The XSetWMHints function sets the window manager hints that include icon 
information and location, the initial state of the window, and whether the appli- 
cation relies on the window manager to get keyboard input. 

XSetWMHints can generate BadAlloc and BadWindow errors. 

To read the window manager hints for a window, use XGetWMHints. 

XSiflints *rS2%t}iimiitB {display, w) 
Display ^display; 
Window w; 

display Specifies the connection to the XwiN server. 

w Specifies the window. 

The XGetWMHints function reads the window manager hints and returns NULL 
if no WM_HINTS property was set on the window or a pointer to a XWMHints 
structure if it succeeds. When finished with the data, free the space used for it 
by calling XFree. 

XGetWMHints can generate a BadWindow error. 
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Setting and Getting Window Sizing Hints 

Xlib provides functions that you can use to set or get window sizing hints. 

The functions discussed in this section use the flags and the XSlzeHlnts struc- 
ture, as defined in the < Xll/Xutil.h > header file: 



/* Size 


hints mask bits 


*/ 




fdefine 


USPosition 


(IL « 0) 


/* user specified x, y */ 


idefine 


USSize 


(IL « 1) 


/* user specified width, hei^t */ 


tdefine 


PPosition 


(IL « 2) 


/* program specified position */ 


fdefine 


PSize 


(Ui « 3) 


/* program specified size */ 


idefine 


PMinSize 


(IL « 4) 


/* program specified minimum size */ 


fdefine 


PMaxSize 


(IL « 5) 


/* program specified maximim size V 


fdefine 


PBesizeInc 


(IL « 6) 


/* program specified resize increments 
*/ 


fdefine 


PAspect 


(IL « 7) 


/* program specified min and max asfpect 
ratios */ 


fdefine 


PAllHints 




(PPosition IPSize IPMinSize IPMaxSize | 
PResizeInc I PUspect ) 



/* Values V 
typedef struct { 

long flags; /* marks Which fields in this structure are defined 

int Xr y; 

int width, height ; 
int minjwidth, min_hei^t; 
int maxjwidth, max_hei^t; 
int width_inc, height_inc; 
struct { 

int x; /* numerator */ 

int y; /* denominator */ 

} minjBLflfpect, maxjaspect; 
} XSizeHints; 
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The X, y, width, and height members describe a desired position and size for the 
window. To indicate that this information was specified by the user, set the 
USPosition and USSize flags. To indicate that it was specified by the applica- 
tion without any user involvement, set PPosition and PSize. This lets a win- 
dow manager kxiow that the user specifically asked where the window should 
be placed or how the window should be sized and that the window manager 
does not have to rely on the program's opinion. 

The min_width and min_height members specify the minimum window size 
that still allows the application to be useful. The max_width and max^height 
members specify the maximum window size. The width_inc and height Jnc 
members define an arithmetic progression of sizes (minimum to maximum) into 
which the window prefers to be resized. The min_aspect and max_aspect 
members are expressed as ratios of x and y, and they allow an application to 
specify the range of aspect ratios it prefers. 

The next two functions set and read the WM_NORMAL_HINTS property. 

To set the size hints for a given window in its normal state, use XSetNor- 
malHints. 

XSetNormalHints {display, w, hints) 
Display *display; 
Window w; 
XSizeHints *hints; 

display Specifies the connection to the XwiN server. 

w Specifies the window. 

hints Specifies a pointer to the size hints for the window in its normal 

state. 

The XSetNorraalHints function sets the size hints structure for the specified 
window. Applications use XSetNormalHints to inform the window manager of 
the size or position desirable for that window. In addition, an application that 
wants to move or resize itself should call XSetNormalHints and specify its new 
desired location and size as well as making direct Xlib calls to move or resize. 
This is because window managers may ignore redirected configure requests, but 
they pay attention to property changes. 
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To set size hints, an application not only must assign values to the appropriate 
members in the hints structure but also must set the flags member of the struc- 
ture to indicate which information is present and where it came from. A call to 
XSetNozinalHints is meaningless, unless the flags member is set to indicate 
which members of the structure have been assigned values. 

XSetNonnalHints can generate BadAlloc and BadWindow errors. 

To return the size hints for a window in its normal state, use XGetNornalHlnts. 

Statxis XSetNormalHints (display, w, hints jetum) 
Display ^display; 
Window w; 

XSizeHints *hintsj€tum; 

display Specifies the connection to the XwiN server. 

w Specifies the window. 

hints jetum Returns the size hints for the window in its normal state. 

The XGetNonnalHints function returns the size hints for a window in its nor- 
mal state. It returns a nonzero status if it succeeds or zero if the application 
specified no normal size hints for this window. 

XGetNonnalHints can generate a BadWindow error. 

The next two functions set and read the WM_ZCX)M_HINTS property. 

To set the zoom hints for a window, use XSetZooraHlnts. 

XSetZoomHints {display, w, zhints) 
Display ^display; 
Window w'r 
XSizeHints "zftmte; 

Specifies the connection to the XwiN server. 
Specifies the window. 
Specifies a pointer to the zoom hints. 



display 
w 

zhints 
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Many window managers think of windows in one of three states: iconic, normal, 
or zoomed. The XSetZocxnHints function provides the window manager with 
information for the window in the zoomed state. 

XSetZooinHints can generate BadAlloc and BadWindow errors. 

To read the zoom hints for a window, use XGetZocanHints. 

status XSetZoooHintfl {display, w, 7Jtints_retum) 
Display *display; 
Window w; 

XSizeHints *zhmtsjretum; 

display Specifies the connection to the XwiN server. 

w Specifies the window. 

zhintsjretum Returns the zoom hints. 

The XGetZooniHints function returns the size hints for a window in its zoomed 
state. It returns a nonzero status if it succeeds or zero if the apphcation 
specified no zoom size hints for this window. 

XGetZooniHints can generate a BadWindow error. 

To set the value of any property of type WM SIZE HINTS, use XSet- 
SizeHints. 

XSetSizeHints (display, w, hints, property) 
Display ^display; 
Window w; 
XSizeHints *hints; 
Atom property; 



display Specifies the connection to the XwiN server. 

w Specifies the window. 

hints Specifies a pointer to the size hints. 

property Specifies the property name. 
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The XSetSizeHints function sets the XSizeHints structure for the named pro- 
perty and the specified window. This is used by XSetNormalHints and XSet- 
ZoomHints, and can be used to set the value of any property of type 
WM_^SIZE_HINTS. Thus, it may be useful if other properties of that type get 
defined. 

XSetSizeHints can generate BadAlloc, BadAtc^ti, and BadWindow errors. 

To read the value of any property of type WM__SIZE_HINTS, use XGet- 
SizeHints. 

status XGetSizeHints {display, w, hints jeturn, froperty) 
Display ^display; 
Window w; 

XSizeHints *hintsjretum; 
Atom property; 

display Specifies the connection to the XwiN server. 

w Specifies the window. 

hints jeturn Returns the size hints. 
property Specifies the property name. 

XGetSizeHints returns the XSizeHints structure for the named property and 
the specified window. This is used by XGetNonnalHints and XGetZooinHints, 
It also can be used to retrieve the value of any property of type 
WM^SIZE^HINTS. Thus, it may be useful if other properties of that type get 
defined. ^tSizeHints returns a nonzero status if a size hint was defined or 
zero otherwise. 

XGetSizeHints can generate BadAtom and BadWindow errors. 
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Setting and Getting Icon Size Hints 

Applications can cooperate with window managers by providing icons in sizes 
supported by a window manager. To communicate the supported icon sizes to 
the applications, a window manager should set the icon size property on the 
root window of the screen. To find out what icon sizes a window manager sup- 
ports, applications should read the icon size property from the root window of 
the screen. 

The functions discussed in this section set or read the WM ICON SIZE pro- 
perty. In addition, they use the XlconSize structure, which is defined in 
< Xll/Xutil.h > and contains: 

typedef struct { 

int minjvidth, minjtieight; 

int maxjiridth, maxjieight; 

int width_inc, height_inc; 
} XloonSize; 

The width Jnc and height Jnc members define an arithmetic progression of sizes 
(minimum to maximum) that represent the supported icon sizes. 

To set the icon size hints for a window, use XSetlconSizes. 

XSetloonSizBB {displaif, w, sizejist, count) 
Display *display; 
Window w; 
XloonSize *sizejist; 
int comt; 

display Specifies the connection to the XWIN server. 

w Specifies the window. 

sizejist Specifies a pointer to the size list. 

count Specifies the number of items in the size list. 

The XSetlconSizes function is used only by window managers to set the sup- 
ported icon sizes. 
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XSetlcx^nSizes can generate BadAlloc and BadWlndow errors. 

To return the icon sizes hints for a window, use XGetIcx)nSizes. 

status XSetloonSizes {display, w, sizejistjetum, amntjetum) 
Display ^display; 
Window w; 

XlconSize **sizejistjretum; 
int *anintjretum; 

display Specifies the connection to the XWIN server. 

w Specifies the window. 

siTxJistjetum 

Returns a pointer to the size list. 
count jetum Returns the number of items in the size Ust. 

The X^tlconSizes function returns zero if a window manager has not set icon 
sizes or nonzero otherwise. XGetlconSizes should be called by an application 
that wants to find out what icon sizes would be most appreciated by the win- 
dow manager under which the application is running. The application should 
then use XSetWMHints to supply the window manager with an icon pixmap or 
window in one of the supported sizes. To free the data allocated in 
sizejist__retum, use XFree. 

XGetlconSizes can generate a BadWlndow error. 

Setting and Getting tiie Ciass of a Window 

Xlib provides functions to set and get the class of a window. These functions 
set and read the WM_CLASS property. In addition, they use the XClassHint 
structure, which is defined in < Xll/Xutil.h > and contains: 

typedef struct { 

char *T^sjf\axDB; 

char *re8jcla88; 
} XClassHint; 



9-18 



Xwin GWS: Xlib - C Language Interface 



Communicating with Window Managers 



The res^name meniber contains the application name, and the res^class member 
contains the application class. Note that the name set in this property may differ 
from the name set as WM_NAME. That is, WM^NAME specifies what should 
be displayed in the title bar and, therefore, can contain temporal information 
(for example, the name of a file currently in an editor's buffer). On the other 
hand, the name specified as part of WM^CLASS is the formal name of the appli- 
cation that should be used when retrieving the application's resources from the 
resource database. 

To set the class of a window, use XSetClassHint. 

XSetClassHint {displajf, w, class Jiints) 
Display *dispUnf; 
Window w; 
XOassHint *dass Jiints; 

display Specifies the connection to the XwiN server. 

w Specifies the window. 

class Jiints Specifies a pointer to a XClassHint structure that is to be used. 

The XSetClassHint function sets the class hint for the specified window. 

XSetClassHint can generate BadAlloc and BadWindow errors. 

To get the class of a window, use XGetClassHint. 

status XGetClassHint {display, w, doss Jiints jetum) 
Display ^display) 
Window w; 

XQassHint *dass Jiints jetum; 

display Specifies the connection to the XwiN server. 

w Specifies the window. 

class Jiints jetum 

Returns the XClassHint structure. 

The XGetClassHint function returns the class of the specified window. To free 
res_name and res^dass when finished with the strings, use XFree. 
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XGetClassHint can generate a BadWlndow error. 

Setting and Getting tlie Transient Property 

An application may want to indicate to the window manager that a transient, 
top-level window (for example, a dialog box) is operating on behalf of (or is 
transient for) another window. To do so, the application would set the 
WM_TRANSIENT_FOR property of the dialog box to be the window ID of its 
main window. Some window managers use this information to unmap an 
application's dialog boxes (for example, when the main application window gets 
iconified). 

The functions discussed in this section set and read the WM_TRANSIENT__FOR 
property. 

To set the WM_TRANSIENT_^FOR property for a window, use XSetTran- 
sientForHint. 

XSetTransientForHint {display, w, fnvpjoindow) 
Display *display; 
Window w; 
Window propjoindaw; 

display Specifies the connection to the XWIN server. 

w Specifies the window. 

propjvindow Specifies the window that the WM_TRANSIENT_FOR property 
is to be set to. 

The XSetTransientForHint function sets the WM_TRANSIENT_FOR property 
of the specified window to the specified prop_window. 

XSetTransientForHint can generate BadAlloc and BadWindow errors. 

To get the WM_^TRANSIENT__FOR value for a window, use XGetTran- 
sientForHint. 
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status XGetTransientForHint {display, w, propjoindowjetum) 
Display ^display; 
Window w; 

Window *propjoindow_retum; 

display Specifies the connection to the XwiN server. 

TV Specifies the window. 

propjmndow_retum 

Returns the WM_TRANSIENT__FOR property of the specified 
window. 

The XGetTransientForHint function returns the WM__TRANSIENT_FOR pro- 
perty for the specified window. 

XGetTransientForHint can generate a BadWindow error. 
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Applications with color palettes, smooth-shaded drawings, or digitized images 
demand large numbers of colors. In addition, these applications often require an 
efficient mapping from color triples to pixel values that display the appropriate 
colors. 

As an example, consider a 3D display program that wants to draw a smoothly 
shaded sphere. At each pixel in the image pf the sphere, the program computes 
the intensity and color of light reflected back to the viewer. The result of each 
computation is a triple of RGB coefficients in the range 0.0 to 1.0. To draw the 
sphere, the program needs a colormap that provides a large range of uniformly 
distributed colors. The colormap should be arranged so that the program can 
convert its RGB triples into pixel values very quickly, because drawing the 
entire sphere requires many such conversions. 

On many current workstations, the display is limited to 256 or fewer colors. 
Applications must allocate colors carefully, not only to make sure they cover the 
entire range they need but also to make use of as many of the available colors 
as possible. On a typical X display, many applications are active at once. Most 
workstations have only one hardware look-up table for colors, so only one 
application colormap can be installed at a given time. The application using the 
installed colormap is displayed correctly, and the other applications "go tech- 
nicolor" and are displayed with false colors. 

As another example, consider a user who is running an image processing pro- 
gram to display earth-resources data. The image processing program needs a 
colormap set up with 8 reds, 8 greens, and 4 blues (a total of 256 colors). 
Because some colors are already in use in the default colormap, the image pro- 
cessing program allocates and installs a new colormap. 

The user decides to alter some of the colors in the image. He invokes a color 
palette program to mix and choose colors. The color palette program also needs 
a colormap with 8 reds, 8 greens, and 4 blues, so just as the image-processing 
program, it must allocate and install a new colormap. 

Because only one colormap can be installed at a time, the color palette may be 
displayed incorrectly whenever the image-processing program is active. Con- 
versely, whenever the palette program is active, the image may be displayed 
incorrectly. The user can never match or compare colors in the palette and 
image. Contention for colormap resources can be reduced if applications with 
similar color needs share colormaps. 
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As another example, the image processing program and the color palette pro- 
gram could share the same colormap if there existed a convention that described 
how the colormap was set up. Whenever either program was active, both would 
be displayed correctly. 

The standard colormap properties define a set of commonly used colormaps. 
Applications that share these colormaps and conventions display true colors 
more often and provide a better interface to the user. 

Standard Colormaps 

Standard colormaps allow applications to share commonly used color resources. 
This allows many applications to be displayed in true colors simultaneously, 
even when each application needs an entirely filled colormap. 

Several standard colormaps are described in this section. Usually, a window 
manager creates these colormaps. Applications should use the standard color- 
maps if they already exist. If the standard colormaps do not exist, you should 
create them by opening a new connection, creating the properties, and setting 
the close-down mode of the connection to RetainPentanent. 

The XStandardColormap structure contains: 

typedef struct { 

Colormap colormap; 

unsigned long redmax; 

unsigned long redjnult; 

unsigned long green jnax; 

unsigned long greenjnilt; 

unsigned long bluejnax; 

unsigned long bluejnult; 

unsigned long base^pixel; 
> XStandardColorma^; 

The colormap member is the colormap created by the XCreateColormap func- 
tion. The red^max, green max, and blue max members give the maximum red, 
green, and blue values, respectively. Each color coefficient ranges from zero to 
its max, inclusive. For example, a common colormap allocation is 3/3/2 (3 
planes for red, 3 planes for green, and 2 planes for blue). This colormap would 
have red_max = 7, green_max = 7, and blue_max = 3. An alternate allocation 
that uses only 216 colors is red_max = 5, green_max = 5, and blue_max = 5. 
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The red_mult, green_mult, and blue_mult members give the scale factors used 
to compose a full pixel value. (See the discussion of the base_j>ixel members for 
further information.) For a 3/3/2 allocation, red_mult might be 32, green jnult 
might be 4, and bluejuult might be 1. For a 6-colors-each allocation, red_mult 
might be 36, green mult might be 6, and blue^mult might be 1. 

The base_pixel member gives the base pixel value used to compose a full pixel 
value. Usually, the base_pixel is obtained from a call to the XAllocColorPlanes 
function. Given integer red, green, and blue coefficients in their appropriate 
ranges, one then can compute a corresponding pixel value by using the follow- 
ing expression: 

r * redjnilt -¥ g * gxeenjiult b * bluejnilt + baMjpixal 

For Grayscale colormaps, only the colormap, red_max, red mult, and 
base^pixel members are defined. The other members are ignored. 

To compute a Grayscale pixel value, use the following expression: 

gray * xedjnalt -l- base^pixBl 

The properties containing the XStandardColontBp information have the type 
RGB_COLOR__MAP. 



Standard Colormap Properties and Atoms 

Several standard colormaps are available. Each standard colormap is defined by 
a property, and each such property is identified by an atom. The following list 
names the atoms and describes the colormap associated with each one. The 
< Xll/Xatom.h > header file contains the definitions for each of the following 
atoms, which are prefixed with XA_. 

RGB DEFAULT^MAP This atom names a property. The value of the pro- 
perty is an XStandardColonnap. 

The property defines an RGB subset of the default 
colormap of the screen. Some applications only need a 
few RGB colors and may be able to allocate them from 
the system default colormap. This is the ideal situa- 
tion because the fewer colormaps that are active in the 
system the more applications are displayed with 
correct colors at all times. 
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RGB BEST MAP 



RGB_RED_MAP 
RGB__GREEN^MAP 
RGB BLUE MAP 



A typical allegation for the RGB DEFAULT MAP on 
8-plane displays is 6 reds, 6 greens, and 6 blues. This 
gives 216 uniformly distributed colors (6 intensities of 
36 different hues) and still leaves 40 elements of a 
256-element colormap available for special-purpose 
colors for text, borders, and so on. 

This atom names a property. The value of the pro- 
perty is an XStandardColonnap. 

The property defines the best RGB colormap available 
on the screen. (Of course, this is a subjective evalua- 
tion.) Many image processing and 3D applications 
need to use all available colormap cells and to distri- 
bute as many perceptually distinct colors as possible 
over those cells. This implies that there may be more 
green values available than red, as well as more green 
or red than blue. 

On an 8-plane Pseudocolor display, RGB BEST MAP 
should be a 3/3/2 allocation. On a 24-plane 
DirectColor display, RGB__BEST_MAP should be an 
8/8/8 allocation. On other displays, the 
RGB_BEST_MAP allocation is purely up to the imple- 
mentor of the display. 



These atoms name properties. The value of each pro- 
perty is an XStandardColonnap. 

The properties define all-red, all-green, and all-blue 
colormaps, respectively. These maps are used by appli- 
cations that want to make color-separated images. For 
example, a user might generate a full-color image on 
an 8-plane display both by rendering an image three 
times (once with high color resolution in red, once 
with green, and once with blue) and by multiply- 
exposing a single frame in a camera. 
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RGB GRAY MAP 



This atom names a property. The value of the pro- 
perty is an XStandardColorniap. 



The property describes the best Grayscale colormap 
available on the screen. As previously mentioned, only 
the colormap, red_max, red_mult, and basejpixel 
members of the XStandardColormap structure are 
used for Grayscale colormaps. 



Getting and Setting an XStandardColormap Structure 



To get the XStandardColorniap structure associated with one of the described 
atoms, use XGetStandardColonnap. 

status XSetStandardColozmap (^is^%, w, colormapjetum, jtroperty) 
Display ^display; 
Window w, 

XStandardColormap *cdlomtajtjretum; 
Atom pwperhf ; /* RGB_BEST_MAP, etc. */ 

display Specifies the connection to the XWIN server. 

w Specifies the window. 

colorTmp_return 

Returns the colormap associated with the specified atom. 
property Specifies the property name. 

The TOetStandardColomiap function returns the colonnap definition associated 
with the atom supplied as the property argument. For example, to fetch the 
standard Grayscale colormap for a display, you use XGetStandardColonnap 
with the following syntax: 

XGetStandardColoziiiap(<^, Def aultRootWindow (dpy) , icnap, X21_RGBJGRAYJ<AP) ; 

Once you have fetched a standard colormap, you can use it to convert RGB 
values into pixel values. For example, given an XStandardColormap structure 
and floating-point RGB coefficients in the range 0.0 to 1.0, you can compose 
pixel values with the following C expression: 
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pixBl - baaejpixal 

•I- ((unsigned long) (0.5 •¥ r * redjnax)) * redjnilt 

+ ((imsigned long) (0.5 + g * greenjnax)) * green_mlt 

•I- ((unsigned long) (0.5 -f b * bluejnax)) * bluejnult; 

The use of addition rather than logical OR for composing pixel values permits 
allocations where the RGB value is not aligned to bit boundaries. 

X(3etStandardColormap can generate BadAtom and BadWindow errors. 

To set a standard colormap, use XSetStandardColonnap. 

XSetStandardColozmap ((^tspky, w, colormap, property) 
Display ^display; 
Window w; 

XStandardColonnap *colormap; 

Atom property; /» RGB__^BEST^MAP, etc. ♦/ 

display Specifies the connection to the Xwnsr server. 

w Specifies the window. 

colormap Specifies the colormap. 

property Specifies the property name. 

The XSetStandardColormap function usually is only used by window 
managers. To create a standard colormap, follow this procedure: 

■ Open a new connection to the same server. 

■ Grab the server. 

■ See if the property is on the property list of the root window for the 
screen. 

■ If the desired property is not present: 

□ Create a colormap (not required for RGB^DEFAULT MAP) 

□ Determine the color capabilities of the display. 

□ Call XAllocColorPlanes or XAllocColorCells to allocate cells in 
the colormap. 



Predefined Property Functions 



9-27 



Manipulating Standard Colormaps 



□ Call XStoreColors to store appropriate color values in the color- 
map. 

□ Fill in the descriptive members in the XStandardColorinap structure. 

□ Attach the property to the root window. 

□ Use XSetCloseDownMode to make the resource permanent. 

□ Ungrab the server. 

XSetStandardColormap can generate BadAlloc, BadAtom, and BadWin- 
dow errors. 
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Once you have initialized the X system, you can use the Xlib utility functions to: 

■ Handle keyboard events 

■ Obtain the X environment defaults 

■ Parse window geometry strings 

■ Parse hardware colors strings 

■ Generate regions 

■ Manipulate regions 

■ Use cut and paste buffers 

■ Determine the appropriate visual 

■ Manipulate images 

■ Manipulate bitmaps 

■ Use the resource manager 

■ Use the context manager 

As a group, the functions discussed in this chapter provide the functionality that 
is frequently needed and that spans toolkits. Many of these functions do not 
generate actual protocol requests to the server. 
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This section discusses keyboard event functions and KeySym classification mac- 
ros. 



Keyboard Event Functions 

The Xwnsr server does not predefine the keyboard to be ASCII characters. It is 
often useful to know that ti\e a key was just pressed or that it was just released. 
When a key is pressed or released, the XWIN server sends keyboard events to 
client programs. The structures associated with keyboard events contain a key- 
code member that assigns a number to each physical key on the keyboard. For 
a discussion of keyboard event processing, see "Keyboard and Pointer Events" 
in Chapter 8. For information on how to manipulate the keyboard encoding, 
see "Keyboard Encoding" in Chapter 7. 

Because KejKTodes are completely arbitrary and may differ from server to 
server, client programs wanting to deal with ASCII text, for example, must 
explicitly convert the Ke)<!ode value into ASCII. Therefore, Xlib provides func- 
tions to help you customize the keyboard layout. Keyboards differ dramati- 
cally, so writing code that presumes the existence of a particular key on the 
main keyboard creates portability problems. 

Keyboard events are usually sent to the deepest viewable window underneath 
the pointer's position that is interested in that type of event. It is also possible 
to assign the keyboard input focus to a specific window. When the input focus 
is attached to a window, keyboard events go to the client that has selected input 
on that window rather than the window under the pointer. 

The functions in this section handle the shift modifier computations suggested 
by the protocol. The KeyS)an table is internally modified to define the lower- 
case transformation of a-z by adding the lowercase KeySym to the first element 
of the KeySym list (used internally) defined for the KeyCode, when the list is of 
length 1. If you want the untransformed KeySyms defined for a key, you 
should only use the functions described under "Keyboard Encoding" in Chapter 
7. 

To look up the KeySyms, use XLookupKeysym. 

KeySym XLookupKeysym(^_ei^^, index) 
XKeyEvent *keyjvent) 
int index; 
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keyjvent 
index 



Specifies the KeyPress or KeyRelease event. 

Specifies the index into the KeySyms list for the event's Key- 
Code. 



The XLookupKeysym function uses a given keyboard event and the index you 
specified to return the KeySym from the list that corresponds to the KeyCode 
member in the XKeyPressedEvent or XKeyReleasedEvent structure. If no 
KeySym is defined for the KeyCode of the event, XLookupKeysym returns 
NoSymbol. 

To refresh the stored modifier and keymap information, use XRef reshKey- 
boardMapping. 

XRBf reahlte^axdMB^dLng {event jmp) 
XMappingEvent *eventjnap; 

event jnap Specifies the mapping event that is to be used. 

The XEtef reshReyboardMapping function refreshes the stored modifier and key- 
map information. You usually call this function when a MappingNotify event 
with a request member of MappingKeyboard or MappingMbdif ier occurs. The 
result is to update Xlib's knowledge of the keyboard. 

To map a key event to an ISO Latin-1 string, use XLookupString. 

int XLoolasjp&trixigimntjtruct, buffer ^return, bytes Jniffer, keysymjretum, statusjnjmt) 
XKeyEvent *eventjstruct; 
ctisa '^bufferjetum; 
int bytes Jmffer; 
KeySym *keysymjetum; 
XComposeStatus ^statusjnjmt; 

event jtruct Specifies the key event structure to be used. You can pass 
XKteyPressedEvent or XlfeyReleasedEvent. 

buffer jetum Returns the translated characters. 

bytes Jjuffer Specifies the length of the buffer. No more than bytes_buffer of 
translation are returned. 
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keysymjetum Returns the KeySym computed from the event if this argument 
is not NULL. 

status Jnj)ut Specifies or returns the XOxiiposeStatus structure or NULL. 

The XLooki;4)String function is a convenience routine that maps a key event to 
an ISO Latin-1 string, using the modifier bits in the key event to deal with shift, 
lock, and control. It returns the translated string into the user's buffer. It also 
detects any rebound KeySyms (see XRebindKeysym) and returns the specified 
bytes. XLookupString returns the length of the string stored in the tag buffer. 
If the lock modifier has the caps lock KeySym associated with it, XLookup- 
String interprets the lock modifier to perform caps lock processing. 

If present (non-NULL), the XCat5)oseStatus structure records the state, which 
is private to Xlib, that needs preservation across calls to XLookupString to 
implement compose processing. 

To rebind the meaning of a KeySym for a client, use XRebindKeysym. 

XRebindKeysym (<2ts^/ay, keysym, list, modjxmnt, string, hytes^string) 
Display *display; 
KeySym keysym; 
KeySym 
int modjcount; 
unsigned char ^string) 
int bytes^string; 



display Specifies the connection to the XwiN server. 

keysym Specifies the KeySym that is to be rebound. 

list Specifies the Ke)^yms to be used as modifiers. 

modjount Specifies the number of modifiers in the modifier list. 

string Specifies a pointer to the string that is copied and will be 
returned by XLookupString. 

bytes jtring Specifies the length of the string. 



The XRebindKeysym function can be used to rebind the meaning of a Kej^ym 
for the client. It does not redefine any key in the XwiN server but merely pro- 
vides an easy way for long strings to be attached to keys. XLookupString 
returns this string when the appropriate set of modifier keys are pressed and 
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when the KeySym would have been used for the translation. Note that you can 
rebind a KeySym that may not exist. 

To convert the name of the KeySym to the KeySym code, use 
XStringToKeysym. 

KeySym XStrtngToKeysym ( sMng) 
char ^string; 

string Specifies the name of the KeySym that is to be converted. 

Valid KeySym names are listed in < Xll/keysymdef .h > by removing the XK_ 
prefix from each name. If the specified string does not match a valid KeySym, 
XStringToKeysym returns NoS^tibol. 

To convert a KeySym code to the name of the KeySym, use XKeysymToString. 

char *XKieysyinToSt ring (fceysym) 
KeySym keysym; 

keysym Specifies the KeySym that is to be converted. 

The returned string is in a static area and must not be modified. If the specified 
KeySym is not defined, XKeysymToString returns a NULL. 

To convert a key code to a defined KeySym, use XKeycodeToKeysym. 

KeySym XKeycodeToKeysym ((2tsp2ay/ key code, index) 
EHsplay * display', 
KeyCode keycode; 
int index; 

display Specifies the connection to the XwiN server. 

keycode Specifies the KeyCode. 

index Specifies the element of KeyCode vector. 

The XKeycxxieToKeysym function uses internal Xlib tables and returns the 
KeySym defined for the specified KeyCode and the element of the KeyCode 
vector. If no symbol is defined, XKeycodeToKeysym returns NoSyrabol. 
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To convert a KeySym to the appropriate KeyCode, use XKeysyirfroKeycode. 

Ke^ode XKBYByaacllltoyoodB {disphnf, keysym) 
Display ^display; 
KeySym Ixysym; 

display Specifies the connection to the XwiN server. 

keysym Specifies the KeyS)™ that is to be searched for. 

If the specified KeySym is not defined for any KeyCode, XKfeysymToKeycode 
returns zero. 

Keysym Classification Macros 

You may want to test if a KeySym is, for example, on the keypad or on one of 
the function keys. You can use the KeySym macros to perform the following 
tests. 

IsCursozJtey ( keysym) 
Returns True if the specified KeySym is a cursor key. 

laFunctionKey ( keysym) 
Returns True if the specified KeySym is a function key. 

IsKeypadKBy {keysym) 
Returns True if the specified KeySym is a keypad key. 

laMlsGFunctionKBy (keysym) 

Returns True if the specified KeySym is a miscellaneous function key. 

IsModif iorltey ( keysym) 
Returns True if the specified KeySym is a modifier key. 

IfliPFKByC Aisysym) 
Returns True if the specified KeySym is a PF key. 
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A program often needs a variety of options in the X environment (for example, 
fonts, colors, mouse, background, text, and cursor). Specifying these options on 
the command line is inefficient and unmanageable because individual users 
have a variety of tastes with regard to window appearance. XGetDef ault 
makes it easy to find out the fonts, colors, and other environment defaults 
favored by a particular user. Defaults are usually loaded into the 
RESOURCE_MANAGER property on the root window at login. If no such pro- 
perty exists, a resource file in the user's home directory is loaded. On a XwiN 
System system, this file is $HOME/.Xdefaults. 

After loading these defaults, XGetDefault merges additional defaults specified 
by the XENVIRONMENT environment variable. If XENVIRONMENT is 
defined, it contains a full path name for the additional resource file. If XEN- 
VIRONMENT is not defined, XGetDefault looks for $HQME/.Xdefaults-nflme, 
where name specifies the name of the machine on which the application is run- 
ning. For details of the format of these files, see "Using the Resource Manager" 
in this chapter. 

The XGetDefault function provides a simple interface for clients not wishing to 
use the X toolkit or the more elaborate interfaces provided by the resource 
manager discussed in "Using the Resource Manager" in this chapter. 

ckiar ^yGetDefaalt {display, jnvgram, option) 
Display ^display; 
char ^program) 
char * option; 

display Specifies the connection to the XwiN server. 

program Specifies the program name for the Xlib defaults (usually argv[0] 

of the main program). 

option Specifies the option name. 

The XGetDefault function returns the value NULL if the option name specified 
in this argument does not exist for the program. The strings returned by XGet- 
Default are owned by Xlib and should not be modified or freed by the client. 

To obtain a pointer to the resource manager string of a display, use 
XResourceManagerString. 
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char *XRa80uroeManagerString (<^tsp2ay) 
Display ^display; 

display Specifies the connection to the XwiN server. 

The XResourceManagerString returns the RESOURCE^MANAGER property 
from the server's root window of screen zero, which was returned when the 
connection was opened using XppenDisplay. 
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To parse standard window geometry strings, use XParseGeometry. 

int XBaraeQ^omtry {parsestring, xjretum, yjretum, width jetum, heightjetum) 
char *parsestring; 
int *x_retum, *yjretum\ 
int *widthjretum, *height_retum; 

parsestring Specifies the string you want to parse. 
x_return 

yjretum Return the x and y offsets. 

tvidth^retum 

heightjetum Return the width and height determined. 

By convention, X applications use a standard string to indicate window size and 
placement. XParseGeanaetry makes it easier to conform to this standard 
because it allows-you to parse the standard window geometry. Specifically, this 
function lets you parse strings of the form: 

[-] [<it7ttit/i>x<*€i;g/ifc>l[{+-}<xo)5feei>{+-}<yc»fi^fc>] 

The items in this form map into the arguments associated with this function. 
(Items enclosed in <> are integers, items in [] are optional, and items enclosed 
in { } indicate "choose one of". Note that the brackets should not appear in the 
actual string.) 

The XParseGeometry function returns a bitmask that indicates which of the four 
values (width, height, xoffset, and yoffset) were actually found in the string and 
whether the x and y values are negative. By convention, -0 is not equal to +0, 
because the user needs to be able to say "position the window relative to the 
right or bottom edge." For each value found, the corresponding argument is 
updated. For each value not found, the argument is left unchanged. The bits 
are represented by XValue, YValue, WidthValue, HeightValue, XNegative, or 
YNegative and are defined in < Xll/Xutil.h >. They will be set whenever 
one of the values is defined or one of the signs is set. 

If the function returns either the XValue or YValue flag, you should place the 
window at the requested position. 
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To parse window geometry given a user-spedfied position and a default posi- 
tion, use XGecxnetry. 

int yD&ouBtry {display, screen, position, default jtosition, hwidth, ftvidth, fheight, xadder, 
yadder, xjetum, yjetum, width jretum, heightjretum) 
Display ^display; 
int screen) 

char ^position, * default jnsition; 

unsigned int hwidth; 

unsigned int fwidth, fheight; 

int xadder, yadder; 

int *x_retum, *y_retum; 

int *widthjetum, *heightjretum; 

display Specifies the connection to the XwiN server. 

screen Specifies the screen. 

position 

defaultj)osition 

Spedfy the geometry specifications. 
btvidth Specifies the border width. 

fheight 

fwidth Specify the font height and width in pixels (increment size). 

xadder 

yadder Specify additional interior padding needed in the window. 

x_return 

yjeturn Return the x and y offsets. 

widthjreturn 

hdghtjreturn Return the width and height determined. 

You pass in the border width (bwidth), size of the increments fwidth and 
fheight (typically font width and height), and any additional interior space 
(xadder and yadder) to make it easy to compute the resulting size. The 
XGeanetry function returns the position the window should be placed given a 
position and a default position. XGeometry determines the placement of a win- 
dow using a geometry specification as specified by XParseGeometry and the 
additional information about the window. Given a fully qualified default 
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geometry specification and an incomplete geometry specification, 
XParseGeoinetry returns a bitmask value as defined above in the 
XParseGeonietry call, by using the position argument. 

The returned width and height will be the width and height specified by 
defaultjx)sition as overridden by any user-specified position. They are not 
affected by fwidth, fheight, xadder, or yadder. The x and y coordinates are 
computed by using the border width, the screen width and height, padding as 
specified by xadder and yadder, and the fheight and fwidth times the width and 
height from the geometry specifications. 
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To parse color values, use XParseColor. 

status IXBaraeColor (display, colormap, spec, exact^defjetum) 
EKsplay ^display; 
Colonnap colormap; 
diar *spec; 

XColor *exactJU^jretum; 

display Specifies the connection to the XwiN server. 

colormap Specifies the colonnap. 

spec Specifies the color name string; case is ignored. 

exadjiefjetum Returns the exact color value for later use and sets the 
DoRed, DoGreen, and DoBlue flags. 

The XParseColor function provides a simple way to create a standard user 
interface to color. It takes a string specification of a color, typically from a com- 
mand line or XGetDefault option, and returns the corresponding red, green, 
and blue values that are suitable for a subsequent call to XAllocColor or 
XStoreColor. The color can be specified either as a color name (as in XAlloc- 
NaxnedColor) or as an initial sharp sign character followed by a numeric 
specification, in one of the following formats: 



The R, G, and B represent single hexadecimal digits (both uppercase and lower- 
case). When fewer than 16 bits each are specified, they represent the most- 
significant bits of the value. For example, #3a7 is the same as #3(XX)a0007000. 
The colormap is used only to determine which screen to look up the color on. 
For example, you can use the screen's default colormap. 

If the initial character is a sharp sign but the string otherwise fails to fit the 
above formats or if the initial character is not a sharp sign and the named color 
does not exist in the server's database, XParseColor fails and returns zero. 

XParseColor can generate a BadColor error. 



#RGB 
#RRGGBB 
#RRRGGGBBB 
#RRRRGGGGBBBB 



(4 bits each) 
(8 bits each) 
(12 bits each) 
(16 bits each) 
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Regions are arbitrary sets of pixel locations. Xlib provides functions for mani- 
pulating regions. The opaque type Region is defined in < Xll/Xutil .h >. 

To generate a region from a polygon, use XPolygonRegion. 

Region XPolygonRsglon (pom^s, n, fUljule) 
XPoint pointsU; 
int n; 

int fill jidk; 

points Specifies an array of points. 

n Specifies the number of points in the polygon. 

filljule Specifies the fill-rule you want to set for the specified GC. You 

can pass EvenOddRule or WindingRule. 

The XPolygonRegion function returns a region for the polygon defined by the 
points array. For an explanation of fill_rule, see XCreateGC. 

To generate the smallest rectangle enclosing the region, use XClipBox. 

XClipBox(r, rectj^tum) 
Region r; 

XRectangle *rect_retum; 

r Specifies the region. 

rectjetum Returns the smallest enclosing rectangle. 

The XClipBox function returns the smallest rectangle enclosing the specified 
region. 
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Xlib provides functions that you can use to manipulate regions. This section 
discusses how to: 

■ Create, copy, or destroy regions 

■ Move or shrink regions 

■ Compute with regions 

■ Determine if regions are empty or equal 

■ Locate a point or rectangle in a region 

Creating, Copying, or Destroying Regions 

To create a new empty region, use XCreateRegion. 

Region XCreateRegion () 

To set the cUp-mask of a GC to a region, use XSetRegion. 

XSetRegion ( display, gc, r) 
Display *display; 
GC gc; 
Region r; 

display Specifies the connection to the XWIN server. 

gc Specifies the GC. 

r Specifies the region. 

The XSetRegion function sets the clip-mask in the GC to the specified region. 
Once it is set in the GC, the region can be destroyed. 

To deallocate the storage associated with a specified region, use XDestroyRe- 
gion. 

XDestroyRegion ( r) 
Region r; 

r Specifies the region. 
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Moving or Shrinking Regions 

To move a region by a specified amount, use XOff set Region. 

3K)ff aetRogion (r, dx, dy) 
Region r; 
int dx, dy) 

r Specifies the region. 

dx 

dy Specify the x and y coordinates, which define the amount you 

want to move the specified region. 

To reduce a region by a specified amount, use XShrinkRegion. 

XShrinkRegion (r, dx, dy) 
Region r; 
int dx, dy; 

r Specifies the region. 

dx 

dy Specify the x and y coordinates, which define the amount you 

want to shrink the specified region. 

Positive values shrink the size of the region, and negative values expand the 
region. 

Computing with Regions 

To compute the intersection of two regions, use XIntersectRegion. 

XIntersectRogion {sra, srh, drjetum) 
Region sra, srb, drjretum; 

sra 

srh Specify the two regions with which you want to perform the 

computation. 
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drjrelurn Returns the result of the computation. 

To compute the union of two regions, use XUnionRegion. 

XUhionRagion (sm, srh, drjretwm) 
Region sru, srb, drjetum; 

sra 

srb Specify the two regions with which you want to perform the 

computation. 

drjreturn Returns the result of the computation. 

To create a union of a source region and a rectangle, use XUnionRectWithRe- 
gion. 

xanionRectWithRegion {rectangle, srcjegum, destjegionjetum) 
XRectangle ^rectangle; 
Region srcjegion; 
Region destjegionjetum', 

rectangle Specifies the rectangle. 

srcjegion Specifies the source region to be used. 

destjegionjetum 

Returns the destination region. 

The XUnionRectWlthReglon function updates the destination region from a 
union of the specified rectangle and the specified source region. 

To subtract two regions, use XSiabtractRegion. 

XSubtractRagion {sra, srh, drjetum) 
Region sra, srb, drjetum*, 

sra 

srh Specify the two regions with which you want to perform the 

computation. 

drjetum Returns the result of the computation. 
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The XSubtractRegion function subtracts srb from sra and stores the results in 
dr_return. 

To calculate the difference between the union and intersection of two regions, 
use XXbrRegion. 

XXorRagion (sra, srb, drjretum) 
Region sra, srb, drjetum; 

sra 

srb Specify the two regions with which you want to perform the 

computation. 

drjretum Returns the result of the computation. 



Determining if Regions Are Empty or Equal 

To determine if the specified region is empty, use XEitptyRegion. 

Bool XEinptyRegion(r) 
Region r; 

r Specifies the region. 

The XEinptyRegion function returns True if the region is empty. 

To determine if two regions have the same offset, size, and shape, use 
XEqualRegion. 

Bool XEqualRegion (rl, r2) 
Region rl,r2; 

rl 

r2 Specify the two regions. 

The XEqualRegion function returns True if the two regions have the same 
offset, size, and shape. 
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Locating a Point or a Rectangle in a Region 

To determine if a specified point resides in a specified region, use XPointlnRe- 
gion. 

Bool XPointmRagion (r, x, y) 
Region r; 
int X, y; 

r Specifies the region. 

X 

y Specify the x and y coordinates, which define the point. 

The XPointlnRegion function returns True if the point (x, y) is contained in 
the region r. 

To determine if a specified rectangle is inside a region, use XRectlnRegion. 

int XRBCtlnBegion {r, x, y, width, height) 
Region r; 
int X, y; 

unsigned int width, height; 
r Specifies the region. 

X 

y Specify the x and y coordinates, which define the coordinates of 

the upper-left comer of the rectangle. 

xvidth 

height Specify the width and height, which define the rectangle . 

The XRectlnRegion function returns Rectanglein if the rectangle is entirely in 
the specified region, Rec±angleOut if the rectangle is entirely out of the 
specified region, and RectanglePart if the rectangle is partially in the specified 
region. 
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Xlib provides functions that you can use to cut and paste buffers for programs 
using this form of communications. Selections are a more useful mechanism for 
interchanging data between clients because typed information can be exchanged. 
X provides property names for properties in which bytes can be stored for 
implementing cut and paste between windows (implemented by use of proper- 
ties on the first root window of the display). It is up to applications to agree on 
how to represent the data in the buffers. The data is most often ISO Latin-1 
text. The atoms for eight such buffer names are provided and can be accessed 
as a ring or as explicit buffers (numbered 0 through 7). New applications are 
encouraged to share data by using selections (see "Selections" in Chapter 4). 

To store data in cut buffer 0, use XStoreBytes. 

XStoraBytes (display, bytes, ribytes) 
Display *display; 
char *bytes; 
int nbytes; 

display Specifies the connection to the XwiN server. 

bytes Specifies the bytes, which are not necessarily ASCII or null- 



Note that the cut buffer's contents need not be text, so zero bytes are not sp>e- 
cial. The cut buffer's contents can be retrieved later by any client calling 
XFetchBytes. 

XStoreBytes can generate a BadAlloc error. 

To store data in a specified cut buffer, use XStoreBu££er. 

XStoaBuftmc (display, bytes, ribytes, bt^er) 
Display ^display; 



terminated. 



nbytes 



Specifies the number of bytes to be stored. 



char *bytes', 
int kbytes; 
iat buffer; 



display 



Specifies the connection to the XwiN server. 
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bytes Specifies the bytes, which are not necessarily ASQI or null- 

terminated. 

nbytes Specifies the number of bytes to be stored. 

buffer Specifies the buffer in which you want to store the bytes. 



If the property for the buffer has never been created, a BadAtora error results. 

XStoreBuf fer can generate BadAlloc and BadAtom errors. 

To return data from cut buffer 0, use XFetchBytes. 

char ^XFetcUBytes {display, nlnftesjetum) 
Display ^display; 
int *hbyUsjetum; 

display Specifies the connection to the XwiN server. 

nhytesjetum Returns the number of bytes in the buffer. 

The XFetchBytes function returns the number of hyies in the nbytes retum 
argument, if the buffer contains data. Otherwise, the function returns NULL 
and sets nbytes to 0. The appropriate amount of storage is allocated and the 
pointer returned. The client must free this storage when finished with it by 
calling XFree. Note that the cut buffer does not necessarily contain text, so it 
may contain embedded zero bytes and may not terminate with a null byte. 

To return data from a specified cut buffer, use XFetchBuf fer. 

char *XFetc2)Buf fer (display, nhytesjetum, buffer) 
Display ^display; 
int *nhytes_retum; 
int buffer; 



display Specifies the connection to the XwiN server. 

nhytesjetum Returns the number of bj^es in the buffer. 

buffer Specifies the buffer from which you want the stored data 

returned. 
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The XFetchBuf fer function returns zero to the nbytes_retum argument if there 
is no data in the buffer. 

XFetchBuffer can generate a BadValue error. 

To rotate the cut buffers, use XRotateBuffers. 

XRotateBuf fers {display, rotate) 
Display *display; 
int rotate; 

display specifies the connection to the XwiN server. 

rotate Specifies how much to rotate the cut buffers. 

The XRotateBuffers function rotates the cut buffers, such that buffer 0 
becomes buffer n, buffer 1 becomes n + 1 mod 8, and so on. This cut buffer 
numbering is global to the display. Note that XRotateBuffers generates Bad- 
Match errors if any of the eight buffers have not been created. 
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A single display can support multiple screens. Each screen can have several dif- 
ferent visual types supported at different depths. You can use the functions 
described in this section to determine which visual to use for your application. 

The functions in this section use the visual information masks and the 
XVisuallnfo structure, which is defined in < Xll/Xutil.h > and contains: 

/* Visual information mask bits */ 



#define VisiialMoMaBk 0x0 

#define VisuallDMafllc 0x1 

#define VisualScraenlfask 0x2 

#define VisualDepthMask 0x4 

#define VisualClasSMask 0x8 

#define VisualRedMaskHaalc 0x10 

#define VisualGreeiMaakMask 0x20 

#defme VisualBlueMaskMask 0x40 

#de£ine VisualColormapSizeMask 0x80 

#defme VisualBitaPeidVSMask 0x100 

#define VisualAllMsuik OxlFF 



/* Values V 

typedef stnact { 

Visual *visual; 
VimiallD visualid; 
int screen; 
unsignad int dapth; 
icit daaa; 

unaigned long xedjnask; 
unaignad long greanjnaak; 
unaignad long bluajnaak; 
dLnt oolorm^^aiza; 
int bitajparjrgb; 
> mauallnfo; 
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To obtain a list of visual information structures that match a specified template, 
use XGetVisuallnfo. 

XVisuallnfo *XGetVi8ualInfo( iisp/^y, vinfojnask, vinfbjemplate, nitemsj'etum) 
Display *display; 
long vinfojnask; 
XVisuallnfo *vinfdjempjate; 
int *nitems_retum; 

display Specifies the connection to the XwiN server. 

vinfojnask Specifies the visual mask value. 

xnnfojemplate Specifies the visual attributes that are to be used in matching the 
visual structures. 

nitemsjreturn Returns the number of matching visual structures. 

The XGetVisuallnfo function returns a list of visual structures that match the 
attributes specified by vinfo_template. If no visual structures match the tem- 
plate using the specified vinfo mask, XGetVisuallnfo returns a NULL. To free 
the data returned by this function, use XFree. 

To obtain the visual information that matches the specified depth and class of 
the screen, use XMatchVisuallnfo. 

status XMatdiVisuallnfo {display, screen, depth, class, vinfojetum) 
Display ^display; 
int screen; 
int depth; 
int doss; 

XVisuallnfo *vmf6jreium; 

display Specifies the connection to the XwiN server. 

screen Specifies the screen. 

depth Specifies the depth of the screen. 

class Specifies the class of the screen. 

vinfojetum Returns the matched visual information. 
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The XMatchVisioallnfo function returns the visual information for a visual that 
matches the specified depth and class for a screen. Because multiple visuals that 
match the specified depth and class can exist, the exact visual chosen is 
undefined. If a visual is found, XMatchVisi^lInf o returns nonzero and the 
information on the visual to vinfo_return. Otherwise, when a visual is not 
found, XMatchVisualInf o returns zero. 
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Xlib provides several functions that perform basic operations on images. All 
operations on images are defined using an Xlxnage structure, as defined in 
< XI 1 /Xlib. h >. Because the number of different types of image formats can 
be very large, this hides details of image storage properly from applications. 

This section describes the functions for generic operations on images. Manufac- 
turers can provide very fast implementations of these for the formats frequently 
encountered on their hardware. These functions are neither sufficient nor desir- 
able to use for general image processing. Rather, they are here to provide 
minimal functions on screen format images. The basic operations for getting 
and putting images are XGet Image and XPut Image. 

Note that no functions have been defined, as yet, to read and write images to 
and from disk files. 

The XIraage structure describes an image as it exists in the client's memory. The 
user can request that some of the members such as height, width, and xoffset be 
changed when the image is sent to the server. Note that bytes_per jine in con- 
cert with offset can be used to extract a subset of the image. Other members 
(for example, byte order, bitmap_unit, and so forth) are characteristics of both 
the image and the server. If these members differ between the image and the 
server, XPut Image makes the appropriate conversions. The first byte of the first 
line of plane n must be located at the address (data + (n * height * 
bytes_per Jine)). For a description of the XIraage structure, see 'Transferring 
Images between Qient and Server" in Chapter 6. 

To allocate sufficient memory for an Xlmage structure, use XCreatelraage. 

XBoaga ^XCreatelmage {display, visual, depih, format, offset, data, width, height, bitmap jjad, 
hytesjperjine) 
Display ^display; 
Visual ^visual; 
unsigned int depth) 
int format) 
\xii offset) 
char *data) 
unsigned int width) 
unsigned int height) 
int bitmap jpad) 
int bytes jper Jine) 
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display Specifies the connection to the XwiN server. 

visml Specifies a pointer to the visual. 

depth Specifies the depth of the image. 

format Specifies the format for the image. You can pass XYBitnvap, 

XYPixmap/ or ZPixmap. 

offset Specifies the ntimber of pixels to ignore at the beginning of the 

scanline. 

data Specifies a pointer to the image data. 

width Specifies the width of the image, in pixels. 

height Specifies the height of the image, in pixels. 

bitmap jpad Specifies the quantum of a scanline (8, 16, or 32). In other 

words, the start of one scanline is separated in client memory 
from ti\e start of the next scanline by an integer multiple of this 
many bits. 



hytesjperjine Specifies the number of bytes in the client image between the 
start of one scanline and the start of the next. 

The XCreatelraage function allocates the memory needed for an Xlmage struc- 
ture for the specified display but does not allocate space for the image itself. 
Rather, it initializes the structure byte-order, bit-order, and bitmap-unit values 
from the display and returns a pointer to the Xlinage structure. The red, green, 
and blue mask values are defined for Z format images only and are derived 
from the Visual structure passed in. Other values also are passed in. The 
offset permits the rapid displaying of the image without requiring each scanline 
to be shifted into position* If you pass a zero value in bytes jperjine, Xlib 
assumes that the scanlines are contiguous in memory and calculates the value of 
bytes_per_line itself. 

Note that when the image is created using XCreatelraage, XGetlraage, or 
XSublraage, the destroy procedure that the XDestroy Image function calls frees 
both the image structure and the data pointed to by the image structure. 

The basic functions used to get a pixel, set a pixel, create a subimage, and add a 
constant offset to a Z format image are defined in the image object. The func- 
tions in this section are really macro invocations of the functions in the image 
object and are defined in < Xll/Xutil.h >. 
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To obtain a pixel value in an image, use XGetPixel. 

unsigmd long XGetP ixal (ximagf, x, y) 
Xlmage *ximage; 
int x; 
int y; 

ximage Specifies a pointer to the innagq. 

X 

y Specify the x and y coordinates. 

The XGetPixel function returns the specified pixel from the named image. The 
pixel value is returned in normalized format (that is, the least-significant byte of 
the long is the least-significant byte of the pixel). The image must contain the x 
and y coordinates. 

To set a pixel value in an image, use XPutPlxel. 

int XPutPlxel (xi'magf, x,y, ptxf/) 
Xlmage *ximage; 
int x; 
int y; 

unsigned long jtixel; 



ximage Specifies a pointer to the image. 

X 

y Specify the x and y coordinates. 

pixel Specifies the new pixel value. 



The XPutPlxel function overwrites the pixel in the named image with the 
specified pixel value. The input pixel vdue must be in normalized format (that 
is, the least-significant byte of the long is the least-significant byte of the pixel). 
The image must contain the x and y coordinates. 

To create a subimage, use XSublnage. 
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Xlmage *XSubImage {xinmge, x, y, subimagejundth, subimagejieight) 
XLnage *ximage; 
int x; 
inty; 

unsigned int subimagejpidth; 
unsigned int subimagejieight; 

ximage Specifies a pointer to the image. 

X 

y Specify the x and y coordinates. 

subimagejundth 

Specifies the width of the new subimage, in pixels. 

subimagejieight 

Specifies the height of the new subimage, in pixels. 

The XSiablinage function creates a new image that is a subsection of an existing 
one. It allocates the memoiy necessary for the new XIrnage structure and 
returns a pointer to the new image. The data is copied from the source image, 
and the image must contain the rectangle defined by x, y, subimage_width, and 
subimage_height. 

To increment each pixel in the pixmap by a constant value, use XAddPixel. 

lOMBixBl {ximage, value) 
Xlmage *ximage; 
long value; 

ximage Specifies a pointer to the image. 

value Specifies the constant value that is to be added. 

The XAddPixel function adds a constant value to every pixel in an image. It is 
useful when you have a base pixel value from allocating color resources and 
need to manipulate the image to that form. 

To deallocate the memory allocated in a previous call to XCreatelraage, use 
XDestroy Image . 

int XDestroylnage (xmia^e) 
Xlmage *ximage; 
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ximage Specifies a pointer to the image. 

The XDestroylnage function deallocates the memory associated with the Xim- 
age structure. 

Note that when the image is created using XCreatelnnage, XGetlxnage, or 
XSublniage, the destroy procedure that this macro calls frees both the image 
structure and the data pointed to by the image structure. 
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Xlib provides functions that you can use to read a bitmap from a file, save a bit- 
map to a file, or create a bitmap. This section describes those functions that 
transfer bitmaps to and from the dienf s file system, thus allowing their reuse in 
a later connection (for example, from an entirely different client or to a different 
display or server). 

The X version 11 bitmap file format is: 

idefine name jwidih width 

#define 7uim£_height height 

#define namejcjxot x 

#define namely Jhot y 

static char nameJA^U = { OxNN,... } 

The variables ending with _x_hot and _y_hot suffixes are optional because they 
are present only if a hotspot has been defined for this bitmap. The other vari- 
ables are required. The J)its array must be large enough to contain the size bit- 
map. The bitmap unit is eight. The name is derived from the name of the file 
that you specified on the original command line by deleting the directory path 
and extension. 

To read a bitmap from a file, use XReadBitxnapFile. 

int XReadBitmapFile {display, d, filename, width jetum, height jetum, hitmapjetum, xjiotjetum. 



Display ^display; 
Drawable d; 
char '^filename; 

unsigned int *widthjretum, *heightjetum; 

Bxmap *bitmapjretum; 

int *xJioijretum, *yJiotjretum; 



widthjeturn 

height jelurn Return the width and height values of the read in bitmap file. 



yjiotjetum) 



display 
d 

filerume 



Specifies the connection to the XwiN server. 

Specifies the drawable that indicates the screen. 

Specifies the file name to use. The format of the file name is 
operating-system dependent. 



10-30 



Xwin GWS: Xlib - C Language Interface 



Manipulating Bitmaps 



Uimapjeturn Returns the bitmap that is created. 
xjiotjetum 

yjiotjetum Return the hotspot coordinates. 

The XReadBitmapFile function reads in a file containing a bitmap. The file can 
be either in the standard X version 10 format (that is, the format used by X ver- 
sion 10 bitmap program) or in the X version 11 bitmap format. If the file cannot 
be opened, XReadBitmapFile returns BitraapOpenFailed. If the file can be 
opened but does not contain valid bitmap data, it returns BitnapFilelnvalid. 
If insufficient working storage is allocated, it returns BitmapNoMemory. If the 
file is readable and valid, it returns BitmapSuccess. 

XReadBitmapFile returns the bitmap's height and width, as read from the file, 
to width_retum and height retum. It then creates a pixmap of the appropriate 
size, reads the bitmap data from the file into the pixmap, and assigns the pix- 
map to the caller's variable bitmap. The caller must free the bitmap using 
XFreePixmap when finished. If mme_xJ\oi and name jyjvoi exist, XReadBit- 
mapFile returns them to x_hot_retum and y_hot_retum; otherwise, it returns 
-1-1. 

XReadBitmapFile can generate BadAlloc and BadDrawable errors. 
To write out a bitmap to a file, use XWriteBitmapFile. 

int XMriteBitmapFile (display, filename, bitmap, width, height, xjiot, yjiot) 
Display *display; 
char "^filename', 
Pixmap bitmap) 
unsigned int width, height) 
int xjnot, yjiot; 



display 


Specifies the connection to the XwiN server. 


filename 


Specifies the file name to use. The format of the file name is 




operating-system dependent. 


bitmap 


Specifies the bitmap. 


width 




height 


Specify the width and height 
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xjwt 

yjiot Specify where to place the hotspot coordinates (or -1,-1 if none 

are present) in the file. 

The XWriteBitanapFile function writes a bitmap out to a file. While 
XReadBitniapFile can read in either X version 10 format or X version 11 for- 
mat, XWriteBitinapFile always writes out X version 11 format. If the file can- 
not be opened for writing, it returns BitmpOpenFailed. If insufficient memory 
is allocated, XWriteBitinapFile returns BitmapNoMemory; otherwise, on no 
error, it returns BitinapSuccess. If x_hot and y_hot are not -1,-1, XWriteBit- 
napFile writes them out as the hotspot coordinates for the bitmap. 

XWriteBitinapFile can generate BadDrawable and BadMatch errors. 

To create a pixmap and then store bitmap-format data into it, use XCreatePix- 
inapFroinBitinapDat a . 

Pixmap XCreatePixmapFroaBitmapData (display, d, data, width, height, fg, hg, depth) 
Display ^display; 
Drawable d; 
char *data; 

unsigned int width, height; 
unsigned long fg, hg; 
unsigned int depth; 



display Specifies the connection to the XwiN server, 

d Specifies the drawable that indicates the screen. 

data Specifies the data in bitmap format. 

rvidth 

height Specify the width and height 

fg 

hg Specify the foreground and background pixel values to use. 

depth Specifies the depth of the pixmap. 



The XCreatePixinapFroniBitinapData function creates a pixmap of the given 
depth and then does a bitmap-format XPutlmage of the data into it. The depth 
must be supported by the screen of the specified drawable, or a BadMatch error 
results. 
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XCreatePixmapFroitiBitmapData can generate BadAlloc and BadMatch errors. 

To include a bitmap written out by XWriteBit:inapFile in a program directly, 
as opposed to reading it in every time at run time, use XCreateBitinapFroinr- 
Data. 

Pixmap XCreateBitiiiaFFroinData(i2ispiay, d, data, width, height) 
Display ^display; 
Drawable d; 
char *data; 

unsigned int width, height; 

display Specifies the connection to the XwiN server. 

d Specifies the drawable that indicates the screen. 

data Specifies the location of the bitmap data. 

width 

height Specify the width and height. 

The XCreateBitinapFroniData function allows you to include in your C pro- 
gram (using #include) a bitmap file that was written out by XWriteBitraapFile 
(X version 11 format only) witiiout reading in the bitmap file. The following 
example creates a gray bitmap: 

iinclude "gray.bitm^" 
Pixmap bitmap; 

bitmap •> XCreateBitmi^FroinData (display, window, gray^bits, gray^width, grayjieight) ; 

If insufficient working storage was allocated, XCreateBitinapFroinData returns 
None. It is your responsibility to free the bitmap using XFreePixmp when 
finished. 

XCreateBitroapFroiriData can generate a BadAlloc error. 
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The resource manager is a database manager with a twist. In most database 
systems, you perform a query using an imprecise specification, and you get 
back a set of records. The resource manager, however, allows you to specify a 
large set of values with an imprecise specification, to query the database with a 
precise specification, and to get back only a single value. This should be used 
by applications that need to know what the user prefers for colors, fonts, and 
other resources. It is this use as a database for dealing with X resources that 
inspired the name "Resource Manager," although the resource manager can be 
and is used in other ways. 

For example, a user of your application may want to specify that all windows 
should have a blue background but that all mail-reading windows should have 
a red background. Presuming that all applications use the resource manager, a 
user can define this information using only two lines of specifications. Your 
personal resource database usually is stored in a file and is loaded onto a server 
property when you log in. This database is retrieved automatically by Xlib 
when a connection is opened. 

As an example of how the resource manager works, consider a mail-reading 
application called xinh. Assume that it is designed so that it uses a complex 
window hierarchy all the way down to individual command buttons, which 
may be actual small subwindows in some toolkits. These are often called 
objects or widgets. In such toolkit systems, each user interface object can be 
composed of other objects and can be assigned a name and a class. Fully 
qualified names or classes can have arbitrary numbers of component names, but 
a fully qualified name always has the same number of component names as a 
fully qualified class. This generally reflects the structure of the application as 
composed of these objects, starting with the application itself. 

For example, the xmh mail program has a name "xmh" and is one of a class of 
"Mail" programs. By convention, the first character of class components is capi- 
talized, and the first letter of name components is in lowercase. Each name and 
class finally has an attribute (for example "foreground" or "font"). If each win- 
dow is properly assigned a name and class, it is easy for the user to specify 
attributes of any portion of the application. 

At the top level, the application might consist of a paned window (that is, a 
window divided into several sections) named "toe". One pane of the paned 
window is a button box window named "buttons" and is filled with command 
buttons. One of these command buttons is used to retrieve (include) new mail 
and has the name "include". This window has a fully qualified name. 
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"xmh.toc.buttons.include'', and a fully qualified class, 
"Xmh.VPaned.Box.Conumnd''. Its fully qualified name is the name of its 
parent, "xmh.tocbuttons'', followed by its name, "include''. Its class is the class 
of its parent, '%nh.VPaned.Box", followed by its particular class, "Command". 
The fully qualified name of a resource is the attribute's name appended to the 
object's fully qualified name, and the fully qualified class is its class appended 
to the object's class. 

This include button needs the following resources: 

■ Title string 

■ Font 

■ Foreground color for its inactive state 

■ Background color for its inactive state 

■ Foreground color for its active state 

■ Background color for its active state 

Each of the resources that this button needs are considered to be attributes of 
the button and, as such, have a name and a class. For example, the foreground 
color for the button in its active state might be named "activeForeground", and 
its class would be "Foreground." 

When an application looks up a resource (for example, a color), it passes the 
complete name and complete class of the resource to a look-up routine. After 
look up, the resource manager returns the resource value and the representation 
type. 

The resource manager allows applications to store resources by an incomplete 
specification of name, class, and a representation type, as well as to retrieve 
them given a fully qualified name and class. 



Application Utility Functions 



10-35 



Using the Resource Manager 



Resource Manager Matching Rules 

The algorithm for determining which resource name or names match a given 
query is the heart of the database. Resources are stored with only partially 
specified names and classes, using pattern matching constructs. An asterisk (*) 
is used to represent any number of intervening components (including none). A 
period (.) is used to separate immediately adjacent components. All queries 
fully specify the name and class of the resowce needed. A trailing period and 
asterisk are not removed. The library supports 100 components in a name or 
class. The look-up algorithm then searches the database for the name that most 
closely matches (is most specific) this full name and class. The rules for a match 
in order of precedence are: 

1 . The attribute of the name and dass must match. For example, queries 
for: 

xterm. Bcxollbar .background (name) 
Xlem. Scrollbar .Background (class) 

will not match the following database entry: 

xterm. scrollbar : on 

2. Database entries with name or class prefixed by a period (.) are more 
specific than those prefixed by an asterisk (*). For example, the entry 
xterm.geometry is more specific than the entry xterm*geometry. 

3. Names are more specific than classes. For example, the entry 
"*scrollbar.background'' is more specific than the entry 
"*Scrollbar.Background''. 

4. Specifying a name or class is more specific than omitting either. For 
example, the entry "Scrollbar*Background" is more specific than the entry 
"♦Background". 

5. Left components are more specific than right components. For example, 
"*vtlOO*background" is more specific than the entry 
"*scrollbar*background'' for the query ''.vtlOO.scrollbar.background". 

6. If neither a period (.) nor an asterisk (*) is specified at the beginning, a 
period (.) is implicit. For example, "xterm.background" is identical to 
".xterm.background". 
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Names and classes can be mixed. As an example of these rules, assume the fol- 



lowing user preference specification: 

xnbMMcdcground: red 

*ooiiiiiand . font : 8x13 

^GGiiinand.baclcgxoiind: blue 

*Coiiiiiand. Foreground: green 

xnh . toc^Comnand. actlvieForeground: black 



A query for the name "xmh.toc.messagefunctions.include.activeForeground'' 
and class "Xmh.VPaned.Box.Command.Foreground" would match 
"xmh.toc*Command.activeForeground" and return "black". However, it also 
matches "*Command.Foreground". 

Using the precedence algorithm described above, the resource manager would 
return the value specified by "xmh.toc*Command.activeForeground". 

Basic Resource Manager Definitions 

The definitions for the resource manager's use are contained in 

< Xll/Xresouroe.h >. Xlib also uses the resource manager internally to allow 

for non-English language error messages. 

Database values consist of a size, an address, and a representation type. The 
size is specified in bytes. The representation type is a way for you to store data 
tagged by some application-defined type (for example, "font" or "color"). It 
has nothing to do with the C data type or with its dass. The XmValue structure 
contains: 

typedef struct ( 

unsigned int size; 

caddrjb addr; 
> XmValue, *XniiValuePtr; 

A resource database is an opaque type used by the look-up functions, 
typedef struct JCnnHashBucketRec *XEiiiDatabase; 
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To initialize the resource manager, use Xmlnitialize. 
void Xnnlnitiali2se < ) ; 

Most uses of the resource manager involve defining names, classes, and 
representation types as string constants. However, always referring to strings in 
the resource manager can be slow, because it is so heavily used in some toolkits. 
To solve this problem, a shorthand for a string is used in place of the string in 
many of the resource manager functions. Simple comparisons can be performed 
rather than string comparisons. The shorthand name for a string is called a 
quark and is the type XritiQuark. On some occasions, you may want to allocate 
a quark that has no string equivalent. 

A quark is to a string what an atom is to a string in the server, but its use is 
entirely local to your application. 

To allocate a new quark, use XrmUniqueQuark. 

XnnQuarlc XxnUniqueQuarlc ( ) 

The XrmUniqueQuark function allocates a quark that is guaranteed not to 
represent any string that is known to the resource manager. 

To allocate some memory you will never give back, use 5q?ernalloc. 

char *3^nnalloc(scze) 
unsigned int sbx; 

The JQpennalloc function is used by some toolkits for permanently allocated 
storage and allows some performance and space savings over the completely 
general memory allocator. 

Each name, class, and representation tj^^e is typedePd as an XntQuark. 

typedef int XnoQuark, ^XniQuarkList; 
typedef XrinQaarlc Xmifaiiie; 
typedef XnnQuark XnnClass; 
typedef XmOaarlc XnaRepresentation; 

Lists are represented as null-terminated arrays of quarks. The size of the array 
must be large enough for the number of components used. 
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typedef XnoQuarlcList XrnilaineList; 
typedbf XmQuarkList XrnCIaBaList; 

To convert a string to a quark, use XrmStringToQuark. 

idefins XrnStringToNaine (string) XnnStringToQuarkC string) 

idefins XnnStringToClass (string) XrmStringToQuark (string) 

idefine XrmStringToRspresentation (string) XnnStringToQuarlc (string) 

XmQuark XnnStringToQuark(sMt^) 
char *strmg; 

string specifies the string for which a quark is to be allocated. 

To convert a quark to a string, use XnnQuarkToString. 

Idefine XoDNaineToString(naiDe) XnnQuarkToString (name) 
Idefine XmClassToString (class) XnnQuarkToString (class) 
Idefine XmRepresentationToString(type) XnnQuarkToString (type) 

char *XnnQuarkToString(^rA:) 
XnnQuark quark; 

quark Specifies the quark for which the equivalent string is desired. 

These functions can be used to convert to and from quark representations. The 
string pointed to by the return value must not be modified or freed. If no string 
exists for that quark, XnnQuarkToString returns NULL. 

To convert a string with one or more components to a quark list use 
XrmStringToQuarkList . 

idefine XnnStringTdltenieList (etr, name) XnnStringToQuarkList ( (atr) , (name)) 
idefine XooStringToClassLiat (str, class) XnnStringToQuarkList ( (str) , (class)) 

void XrmStringToQuarkList {string, qmrks_retum) 
char ^string; 

XnnQuarklist qmrksjreium; 
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string Spedfies the string for which a quark is to be allocated. 

qmrksjetum Returns the list of quarks. 

The XrniStringToQuarkList function converts the null-terminated string (gen- 
erally a fully qualified name) to a list of quarks. The components of the string 
are separated by a period or asterisk character. 

A binding list is a list of type XnnBindingList and indicates if components of 
name or class lists are bound tightly or loosely (that is, if wildcarding of inter- 
mediate components is specified). 

typedef enum {XniBlndTi^tly, XrsoBindLoosaly} XnoBinding, *XnnBindingList; 

XrmBindTightly indicates that a period separates the components, and 
XrmBindLoosely indicates that an asterisk separates the components. 

To convert a string with one or more components to a binding list and a quark 
list, use XnnStrlngToBlndlngQuarkLlst. 

XrmStringToBindingQuarkList {string, bindings jetum, qmrksjetum) 
char ^string; 

XrmBindingList hmdingsjretum; 
XrmQuarklist qmrksjetum; 

string Specifies the string for which a quark is to be allocated. 

bindings_return 

Returns the binding list. The caller must allocate sufficient 
space for the binding list before calling XnnStringToBin- 
dingQuarkList. 

qmrksjetum Returns the list of quarks. The caller must allocate sufficient 
space for the quarks list before calling XrniStrlngToBln- 
dlngQuarkList. 

Component names in the list are separated by a period or an asterisk character. 
If the string does not start with a period or an asterisk, a period is assumed. 
For example, "*a.b*c" becomes: 

quarks a b o 

bindings loose tight loose 
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Resource Database Access 

Xlib provides resource management functions that you can use to manipulate 
resource databases. The next sections discuss how to: 

■ Store and get resources 

■ Get database levels 

■ Merge two databases 

■ Retrieve and store databases 

Storing Into a Resource Database 

To store resources into the database, use XrraPutResource or 
XrmQPut Resource. Both functions take a partial resource specification, a 
representation type, and a value. This value is copied into the specified data- 
base. 

void Xrmi^tResourae {database, specifier, type, value) 
XrmDatabase ^database; 
char *specifier; 
char *hfpe; 
XnnValue *value; 

database Specifies a pointer to the resource database. 

specifier Specifies a complete or partial specification of the resource. 

type Specifies the type of the resource. 

value Specifies the value of the resource, which is specified as a string. 

If database contains NULL, XnnPutResource creates a new database and 
returns a pointer to it. XnnPutResource is a convenience function that calls 
XrinStringTbBindingQuarkList followed by: 

XrnQPutBftsouroe (database, bindings, quarks, XnnStringToQuarkCtype) , valiie) 



Application Utility Functions 



10-41 



Using the Resource Manager 



void XmQPutRasouroe {database, bindings, quarks, type, value) 
XnnDatabase *database; 
XnnBindingList bindings; 
XrmQuarklist quarks; 
XrmRepresentation type; 
XrmValue * value; 



database 


Specifies a pointer to the resource database. 


bindings 


Specifies a list of bindings. 


quarks 


Specifies the complete or partial name or the class list of the 




resource. 


type 


Specifies the type of the resource. 


value 


Specifies the value of the resource, which is si:)ecified as a string. 



If database contains NULL, XrmQPutResource creates a new database and 
returns a pointer to it. 

To add a resource that is specified as a string, use XnnPutStringResource. 

void XmPutStringBesouroe {database, specifier, value) 
XrmDatabase *dataibase; 
char ^specifier; 
char *vaiue; 

database Specifies a pointer to the resource database. 

specifier Specifies a complete or partial specification of the resource. 

value Specifies the value of the resource, which is specified as a string. 

If database contains NULL, XnnPutStringResource creates a new database and 
returns a pointer to it. XrraPutStringResource adds a resource with the 
specified value to the specified database. XrraPutStringResource is a conveni- 
ence routine that takes both the resource and value as null-terminated strings, 
converts them to quarks, and then calls XrraQPutResoiurce, using a "String'' 
representation type. 
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To add a string resource using quarks as a spediication, use 
XrrnQPutSt ringResource . 

void XtnQPutStrin^leaouroe {database, bindings, quarks, value) 
XrmDatabase ^database; 
XraiBindingList bindings; 
XrmQuarklist quarks; 
char *value; 



database Specifies a pointer to the resource database. 

bindings Specifies a list of bindings. 

quarks Specifies the complete or partial name or the class list of the 

resource. 

value Specifies the value of the resource, which is specified as a string. 



If database contains NULL, XnrOPutStringResource creates a new database 
and returns a pointer to it. XrnQPutStringResource is a convenience routine 
that constructs an XrmValue for the value string (by calling strlen to compute 
the size) and then calls XnnQPutResource, using a "String" representation type. 

To add a single resource entry that is specified as a string that contains both a 
name and a value, use XnnPutLineResource. 

void XmiPutLineResotiroe {database, line) 
XnnDaiabase ^database; 
char Vine; 

database Specifies a pointer to the resource database. 

line Specifies the resource value pair as a single string. A single 

colon (:) separates the name from the value. 

If database contains NULL, XnnPutLineResource creates a new database and 
returns a pointer to it. XnnPutLineResource adds a single resource entry to 
the specified database. Any white space before or after the name or colon in the 
line argument is ignored. The value is terminated by a new-line or a NULL 
character. To allow values to contain embedded new-line characters, a "\n" is 
recognized and replaced by a new-line character. For example, line nught have 
the value "xterm*background:greenW. Null-terminated strings without a new 
line are also permitted. 
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Looking Up from a Resource Database 

To retrieve a resource from a resource database, use XrmGetResource or 
XrmQGet Resource . 

Bool XnnGetBesouroe (database, strjiame, strj:lass, strjy^jetum, value jetwm) 
XrmDatabase database; 
char *strjtame; 
char *str_class; 
char **strjypejretum; 
XrmValue *valuejetum; 

database Specifies the database that is to be used. 

strjiame Specifies the fully qualified name of the value being retrieved 

(as a string). 

strj:lass Specifies the fully qualified class of the value being retrieved (as 

a string). 

strtypereturn 

Returns a pointer to the representation type of the destination 
(as a string). 

value jretum Returns the value in the database. 

Bool XmQGetResouroe (database, quark jiame, quark jiass, quarkjyjtejetum, value jetum) 
XrmDatabase database) 
XrmNameList quarkjtame; 
XrmClassList quark j:1ass; 
XrmRepresentation *quarkjypejretwm; 
XrmValue *vdluejetum; 

database Specifies the database that is to be used. 

quark jrnne Specifies the fully qualified name of the value being retrieved 
(as a quark). 

quark_class Specifies the fully qualified dass of the value being retrieved (as 
a quark). 
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quarkjype_return 

Returns a pointer to the representation type of the destination 
(as a quark). 

value jelum Returns the value in the database. 

The XmiGetResource and XrnQGet Re source functions retrieve a resource from 
the specified database. Both take a fully qualified name/class pair, a destination 
resource representation, and the address of a value (size/address pair). The 
value and returned type point into database memory; therefore, you must not 
modify the data. 

The database only frees or overwrites entries on XnnPutResource, 
XrmQPutResource, or XmMergeDatabases. A client that is not storing new 
values into the database or is not merging the database should be safe using the 
address passed back at any time until it exits. If a resource was found, both 
XmiGetResource and XrnnQGetResource return True; otherwise, they return 
False. 

Database Search Lists 

Most applications and toolkits do not make random probes into a resource data- 
base to fetch resources. The X toolkit access pattern for a resource database is 
quite stylized. A series of from 1 to 20 probes are made with only the last 
name/class differing in each probe. The XmiGetResource function is at worst a 
* 2" algorithm, where n is the length of the name/class list. This can be 
improved upon by the application programmer by prefetching a list of database 
levels that nught match the first part of a name/class list. 

To return a list of database levels, use XntiQGetSearchList. 

typedaf XooHashTable *XEiiiSea£c^8t; 

Bool XraQGetSearchList {database, names, dosses, Ust^rehim, Ustjength) 
XnnDatabase database; 
XnnNamelist natnesi 
XrmClassList classes; 
XnnSearchlist listjretum; 
int listJengOi; 
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database 



Specifies the database that is to be used. 
Specifies a list of resource names. 
Specifies a list of resource classes. 



names 



classes 



listjetum Returns a search list for further use. The caller must allocate 
sufficient space for the list before calling XrmQGetSearchList. 



The XnnQGetSearchList function takes a list of names and classes and returns 
a list of database levels where a match might occur. The returned list is in 
best-to-worst order and uses the same algorithm as XrniGetResource for deter- 
mining precedence. If list_retum was large enough for the search list, XnnQGet- 
SearchList returns True; otherwise, it returns False. 

The size of the search list that the caller must allocate is dependent upon the 
number of levels and wildcards in the resource specifiers that are stored in the 
database. The worst case length is 3", where n is the number of name or class 
components in names or classes. 

When using XnnQGetSearchList followed by multiple probes for resources 
with a common name and class prefix, only ttie common prefix should be 
specified in the name and dass list to XnnQGetSearchList. 

To search resource database levels for a given resource, use 
XnnQGet SearchResource . 

Bool XraQG^tSMrcbRttsouroe {list, name, dass, typejetum, vdmjetum) 
XrinSearchList lisi; 
XrmName name; 
XrmGass chss; 

XnnRepresentatiQn ^typejetum; 
XrmValue *valuej€tum; 

list Specifies the search list returned by XnnQGetSearchList. 

name Specifies the resource name. 

class Specifies the resource class. 



listjength 



Specifies the number of enbies (not the byte size) allocated for 
list return. 



10-46 



Xwin GWS: Xlib - C Language Interface 



Using the Resource Manager 



typejetum Returns data representation type. 
valuejetum Returns the value in the database. 

The XntQGetSearchResource function searches the specified database levels for 
the resource that is fully identified by the specified name and class. The search 
stops with the first match. XmOGetSearchResource returns True if the 
resource was found; otherwise, it returns False. 

A call to XrnQGetSearchList with a name and class list containing all 
but the last component of a resource name followed by a call to 
XrrnQGetSearchResource with the last component name and class returns the 
same database entry as XmiGetResource and XnnQGetResource with the fully 
qualified name and class. 

Merging Resource Databases 

To merge the contents of one database into another database, use XrnMergeDa- 
tabases. 

void XrnMargeDatabases {source JEb, target JEb) 
XrmDatabase source JEb, *target_db; 

source jib Specifies the resource database that is to be merged into the tar- 
get database. 

target_db Specifies a pointer to the resource database into which the 
source database is to be merged. 

The XmMergeDatabases function merges the contents of one database into 
another. It may overwrite entries in the destination database. This function is 
u^ to combine databases (for example, an application specific database of 
defaults and a database of user preferences). The merge is destructive; that is, 
the source database is destroyed. 

Retrieving and Storing Databases 

To retrieve a database from disk, use XrniGetFileDatabase. 

XnnDatabase XEnGetFileDatabase(^Zemime) 
char ^filename; 
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filemme Specifies the resource database file name. 

The XrmGetFlleDatabase function opens the specified file, creates a new 
resource database, and loads it with the specifications read in from the specified 
file. The specified file must contain lines in the format accepted by 
XrmPutLineResource. If it cannot open the specified file, XmnGetFileData- 
base returns NULL. 

To store a copy of a database to disk, use xmPutFlleDatabase. 

void XrnPutFll^DatabaM {dat(ibase, stored Jh) 
XrmDatabase database; 
char *stored^db; 

database Specifies the database that is to be used. 

stored_db Specifies the file name for the stored database. 

The XzmPutFileDatabase function stores a copy of the specified database in 
the specified file. The file is an ASQI text file that contains lines in the format 
that is accepted by XrmPutLineResource. 

To create a database from a string, use XrmGetStrin^atabase. 

XmDatabase XxstCetStria^atabaae (data) 
char *data; 

data Specifies the database contents using a string. 

The XrniGetStringDatabase function creates a new database and stores the 
resources specified in the specified nuU-tenninated string. XrniGetStringData- 
base is similar to XrmGetFileDatabase except that it reads the information out 
of a string instead of out of a file. Each line is separated by a new-line character 
in the format accepted by XrniPutLineResource. 
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Parsing Command Line Options 



The XrmParseCOTTOand function can be used to parse the conunand line argu- 
ments to a program and modify a resource database with selected entries from 
the command line. 



/* ValuA is specified in Opt ionDescilBC. value */ 

/* Value is the option string itself */ 

/* Value is characters imnediately following option */ 

/* Value is next argument in argv V 

/* Resoiiroe and value in next argument in argv */ 

/* Ignore this option and the next argument in argv */ 

/* Ignore this option and the rest of argv */ 



typedef en\M ( 
Xrmopt ionNoArg, 
XrmoptionlsArg, 
XrmoptionStickyArg, 
XnnoptionSepArg, 
XrmoptionResArg, 
XrmoptionSldpArg, 
XrmoptionSkipLine 

} XmOptioriKind; 



typedef struct { 

char *option; /* Option specification string in argv */ 

char *resouroeltame; /* Binding and resource name (sans application name) */ 

XrmOptionKind argKind; /* Which style of option it is */ 

caddrjt value; /* Value to provide if Xnnoptionll6Arg */ 

> XnoOptionDesdRec, ^XmpptionDescList; 

To load a resource database from a C command line, use XrmParseConiraand. 

void XmParseComnand ( database, table, table jxmnt, name, argcjnjmt, argvjnjmt,) 
ymDatahase ^database; 
XrmOptionDescList table; 
int tMejount; 
diar *iiame; 
int *argcjnjmt; 
diar **argvjnjmt; 

database Specifies a pointer to the resource database. 

table Specifies the table of command line arguments to be parsed. 

table j:ount Specifies the number of entries in the table. 
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name Specifies the application name. 

argcjnj)ut Specifies the number of arguments and returns the number of 
remaining arguments. 

argvjnj)ut Specifies a pointer to the command line arguments and returns 
the remaining arguments. 

The XrmParseCcOTnand function parses an (argc, argv) pair according to the 
specified option table, loads recognized options into the specified database with 
type "String," and modifies the (argc, argv) pair to remove all recognized 
options. 

The specified table is used to parse the command line. Recognized entries in 
the table are removed from argv, and entries are made in the specified resource 
database. The table entries contain information on the option string, the option 
name, the style of option, and a value to provide if the option kind is Xrmop- 
tionNoArg. The argc argument specifies the number of arguments in argv and 
is set to the remaining number of arguments that were not parsed. The name 
argument should be ttie name of your application for use in building the data- 
base entry. The name argument is prefixed to the resourceName in the option 
table before storing the specification. No separating (binding) character is 
inserted. The table must contain either a period (.) or an asterisk (*) as the first 
character in each resourceName entry. To specify a more completely qualified 
resource name, the resourceName entry can contain multiple components. 

For example, the following is part of the standard option table from the X 
Toolkit Xtlnitialize function: 
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static XmOptionDescBec opTable[] - ( 



{ "-baclcground" , 


" "backgrouna" , 


XrmoptionSepllrg, 


(caddr_t) 


NULL), 


1 II WaJII 


" "Dordercolor" , 


Xnnopt ittiSepArg, 


(caifinr_t) 






" *bacilcground" , 


XcmoptionSepArg, 


(cacicLc^t) 


NULL), 


t ~JX)]xiorwiatn*' r 


" *TopLevexsiiell . tx>rderwiatn*' , 


XimoptionSeiArg, 


(cadcurjci 


NULL), 


f if ^ » ^ amII 

i ""Doraercolor" r 


11 » - a^ri^ 1 amIi 

" ^oordezcoxor " , 


XrmoptionSep]U?g, 


(caddr^t) 


NULL), 


{ "-bw" , 


" *TopLevelSbell . borderWidth" , 


XrmoptionSepArg, 


(caddr^t) 


NULL), 


("-oisplay". 


" .oisplay". 


XrmoptionSepllrg, 


(caddr^t) 


NULL), 


{"-fg", 


" *f oreground" , 


Xrmopt ionSepArg, 


(caddr_t) 


NULL), 


{"-fn". 


"*font". 


XrmoptionSepArg, 


(caddr^t) 


NULL), 












{"-foreground". 


"♦foreground". 


XrmoptionSepIlrg, 


(caddr_t) 


NULL), 


{"-geometry". 


" . TopLevelShell . geometry" , 


XrmoptionSepArg, 


(caddr^t) 


NULL), 


{"-iconic". 


" .Toi^velShell. iconic". 


XimoptionMoArg, 


(caddrjt) 


"on"). 


{"-name", 


".name". 


XrmoptionSepArg, 


(caddr_t) 


NULL), 


{"-reverse". 


"♦reverseVideo", 


XrmoptionNoArg, 


(caddr_t) 


"on"). 


{"-rv". 


"*reverseVideo", 


XrmoptionNoArg, 


(caddr_t) 


"on"). 


{ "-synchronous". 


".synchronous". 


XrmoptionNoArg, 


(caddr__t) 


"on"). 


{"-title". 


" .TopLevelShell. title". 


XrmoptionSepArg, 


(caddr_t) 


NULL), 


{"-xrm". 


NOLL, 


XrmoptionResArg, 


(caddrjt) 


NULL), 



In this table, if the -background (or -bg) option is used to set background 
colors, the stored resource specifier matches all resources of attribute back- 
ground. If the -borderwidth option is used, the stored resource specifier applies 
only to border width attributes of class TopLevelShell (that is, outer-most win- 
dows, including pop-up windows). If the -title option is used to set a window 
name, only the topmost application windows receive the resource. 

When parsing the command line, any unique unambiguous abbreviation for an 
option name in the table is considered a match for the option. Note that upper- 
case and lowercase matter. 
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Using the Context Manager 



The context manager provides a way of associating data with a window in your 
program. Note that tWs is local to your program; the data is not stored in the 
server on a property list. Any amount of data in any number of pieces can be 
associated with a window, and each piece of data has a type associated with it. 
The context manager requires knowledge of the window and type to store or 
retrieve data. 

Essentially, the context manager can be viewed as a two-dimensional, sparse 
array: one dimension is subscripted by the window and the other by a context 
type field. Each entry in the array contains a pointer to the data. Xlib provides 
context management functions with which you can save data values, get data 
values, delete entries, and create a unique context type. The symbols used are 
in<Xll/Xutil.h >. 

To save a data value that corresponds to a window and context type, use 
XSaveContext. 

int XSaveContext {display, w, context, data) 
Display ^display; 
Window w; 
XContext context; 
caddr_t data; 

display Specifies the connection to the XwiN server. 

w Specifies the window with which the data is associated. 

context Specifies the context type to which the data belongs. 

data Specifies the data to be associated with the window and type. 

If an entry with the specified window and type already exists, XSaveContext 
overrides it with the specified context. The XSaveContext function returns a 
nonzero error code if an error has occurred and zero otherwise. Possible errors 
are XCNOMEM (out of memory). 

To get the data associated with a window and type, use XFindContext. 
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int XFindContext (display, w, context, datajetum) 
Display ^dispUnf; 
Window w; 
XContext context; 
caddr_t * datajetum; 



display Specifies the connection to the Xwnsr server. 

w Specifies the window with which the data is associated. 

context Specifies the context type to which the data belongs. 

datajetum Returns a pointer to the data. 



Because it is a return value, the data is a pointer. The XFindContext function 
returns a nonzero error code if an error has occurred and zero otherwise. Possi- 
ble errors are KH)ENT (context-not-found). 

To delete an entry for a given window and type, use XDeleteContext. 

int XDeleteContext (iispZay, contexO 
Display *display; 
Window w; 
XContext context; 

display Specifies the connection to the XwiN server. 

w Specifies the window with which the data is associated. 

context Specifies the context type to which the data belongs. 

The XDeleteContext function deletes the entry for the given window and type 
from the data structure. This function returns the same error codes that 
XFindContext returns if called with the same arguments. XDeleteContext 
does not free the data whose address was saved. 

To create a unique context type that may be used in subsequent calls to 
XSaveContext and XFindContext, use XUniqueContext. 

XContext XUniqueContext () 
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Xlib Functions and Protocol 
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Xlib Functions and Protocoi Requests a-i 
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Xlib Functions and Protocol Requests 



This appendix provides two tables that relate to Xlib functions and the X proto- 
col. The following table lists each Xlib function (in alphabetical order) and the 
corresponding protocol request that it generates. 



Xlib Function 



Protocol Request 



XActivateScreenSaver 

XAddHost 

XAddHosts 

XAddToSaveSet 

XAllocColor 

XAllocColorCells 

XAllocColorPlanes 

XAllocNamedColor 

XAllowEvents 

XAutoRepeatOff 

XAutoRepeatOn 

XBell 

XChangeActivePointeiGrab 
XC3iangeGC 

XOiangeKeyboardControl 

XChangeKeyboardMapping 

XChangePointerControl 

XChangeProperty 

XChangeSaveSet 

XChangeWindowAttributes 

XCirculateSubwindows 

XCirculateSubwindowsDown 

XQrculateSubwindowsUp 

XQearArea 

XQearWindow 

XConfigureWindow 

XConvertSelection 

XCopyArea 

XCop5<IolonnapAndFree 

XCopyGC 

XCopyPlane 



ForceScreenSaver 

ChangeHosts 

ChangeHosts 

ChangeSaveSet 

AllocColor 

AllocColorCells 

AllocColorPlanes 

AllocNamedColor 

AllowEvents 

ChangeKeyboardControl 

ChangeKeyboardControl 

Bell 

QiangeActivePointeiGrab 
ChangeGC 

ChangeKeyboardControl 

ChangeKeyboardMapping 

ChangePointerControl 

ChangeProperty 

ChangeSaveSet 

ChangeWindowAttributes 

CirculateWindow 

QrculateWindow 

QrculateWindow 

Gear Area 

QearArea 

ConfigureWindow 

ConvertSelection 

CopyArea 

CopyColormapAndFree 

CopyCC 

CopyPlane 
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Xlib Function 


Protocol Request 


XCreateBitmapFromData 


CreateGC 




CreatePixmap 




FreeGC 




Putlmage 


XCreateColormap 


CreateColormap 


XCreateFontCursor 


CreateGlyphCursor 


XCreateGC 


CreateGC 


XCreateGlyphCursor 


CreateGlyphCursor 


XCreatePixmap 


CreatePbcmap 


XCreatePixmapCursor 


CreateCursor 


XCreatePixmapFromData 


CreateGC 




CreatePixmap 




FreeGC 




Putlmage 


XCreateSimpleWindow 


CreateWindow 


XCreateWindow 


CreateWindow 


XDefineCursor 


ChangeWindowAttributes 


XDeleteProperty 


DeleteProperty 


XDestroySubwindows 


DestroySubwindows 


XDestroyWindow 


DestroyWindow 


XDisableAccessControl 


SetAccessControl 


XDrawArc 


PolyArc 


XDrawArcs 


PolyArc 


XDrawImageString 


ImageTextS 


XDrawImageStringl6 


ImageTextl6 


XDrawLine 


PolySegment 


XDrawLines 


Polyline 


XDrawPoint 


PolyPoint 


XDrawPoints 


PolyPoint 


XDrawRectangle 


PolyRectangle 


XE)rawRectangles 


PolyRectangle 


XDrawSegments 


PolySegment 


XDrawString 


PolyTextS 


XDrawStringie 


PolyTextl6 


XDrawText 


PolyTextS 
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Xlib Function 


ProtCKol Request 


XDrawTextl6 


PolyTextl6 


XEnableAccessControl 


SetAccessControl 


XFetchBytes 


GetProperty 


XFetchName 


VJWUL A V/L/V-A ijr 


XFillArc 


PolvFillArc 


XFillArcs 


PolvFillArc 


XFillPolvcon 


FillPoly 


XFillRectangle 


PolyFillRectangle 


XFillRectanfi:les 


PolvFillRectanffle 


XForceScrGGnSaver 


FoiveSrrppnSaver 

X v/x ^wk/v>x i^^tn. V ^x 


XFreeColormap 


FreeColormap 


XFreeColors 


FreeColors 


XFreeCursor 


FreeCursor 


XFreeFont 


QoseFont 


XFreeGC 


FreeGC 


XFreePixmap 


FreePixmap 


XGetAtomName 


GetAtomName 


XGetFontPath 


GetFontPath 


XGetGeometry 


GetGeometry 


XGetlconSizes 


GetProDertv 


XGetlniage 


Getlmage 


XGetlnputPocus 


GetlnputFocus 


XGetKeyboardControl 


GetKeyboardControl 


XGetKeyboardMapping 


GetKeyboardMapping 


XGetModifierMapping 


GetModifierMapping 


XGetMotionEvents 


GetMotionEvents 


XGetNormalHints 


GetProperty 


XGetPointerControl 


GetPointerControl 


XGetPointerMapping 


GetPointerMapping 


XGetScreenSaver 


GetScreenSaver 


XGetSelectionOwner 


GetSelectionOwner 


XGetSizeHints 


GetProperty 


XGetWMHints 


GetProperty 


XGetWindowAttributes 


GetWindowAttributes 




GetGeometry 
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Xlib Function 



XGetWindowProperty 

XGetZoomHints 

XGrabButton 

XGrabKey 

XGrabKeyboard 

XGrabPointer 

XGrabServer 

XInitExtension 

XInstallColonnap 

XIntemAtom 

XKillClient 

XListExtensions 

XUstFonts 

XListFontsWithlnfo 

XListHosts 

XListlnstalledColormaps 
XListProperties 
XLoadFont 
XLoadQueryFont 

XLookupColor 

XLowerWindow 

XMapRaised 

XMapSubwindows 

XMapWindow 

XMoveResizeWindow 

XMoveWindow 

XNoOp 

XOpenDisplay 

XParseColor 

XPutlmage 

XQueryBestCursor 

XQueiyBestSize 

XQueryBestStipple 
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Protocol Request 



GetProperty 

GetProperty 

GrabButton 

GrabKey 

GrabKeyboard 

GrabPointer 

GrabServer 

QueryExtension 

InstallColormap 

IntemAtom 

KillClient 

UstExtensions 

listFonts 

UstFontsWithlnfo 

ListHosts 

ListlnstalledColormaps 

ListProperties 

OpenFont 

(^jenFont 

QueryFont 

LookupColor 

ConfigureWindow 

ConfigureWindow 

MapWindow 

MapSubwindows 

MapWindow 

ConfigureWindow 

ConfigureWindow 

NoOperation 

CreateGC 

LookupColor 

Putlmage 

QueryBestSize 

QueryBestSize 

QueryBestSize 
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Xlib Function 


Protocol Request 


XQueryBestTile 


QueryBestSize 


XQueiyColor 


QueryColors 


XQueryColors 


QueryColors 


XQueryExtension 


QueryExtension 


XQueryFont 


QueryFont 


XQueryKeymap 


QueryKeymap 


XQueryPointer 


QueryPointer 


XQueryTextExtents 


OuervTextExtents 


XQueryTextExtentsl6 


QueryTextExtents 


XQueryTree 


QueryTree 


XRaiseWindow 


ConfigureWindow 


XReadBitmapFile 


CreateGC 




CreatePixmap 




FreeGC 




Putlmage 


XRecolorCursor 


RecolorCursor 


XRemoveFromSaveSet 


ChaneeSaveSet 


XRemoveHost 


ChangeHosts 


XRemoveHosts 


ChanffeHosts 


XReparentWindow 


ReparentWindow 


XResetScreenSaver 


ForceScreenSaver 


XResizeWindow 


ConfigureWindow 


XRestackWindows 


ConfigureWindow 


XRotateBuffers 


RotateProperties 
* 


XRotateWindowProperties 


RotateProperties 


XSelectlnput 


ChangeWindow Attributes 


XSendEvent 


SendEvent 


XSetAccessControl 


SetAccessControl 


XSetArcMode 


ChangeGC 


XSetBackground 


ChangeGC 


XSetClipMask 


ChangeGC 


XSetClipOrigin 


ChangeGC 


XSetClipRectangles 


SetClipRectangles 


XSetCloseDownMode 


SetCloseEtownMode 


XSetCommand 


ChangeProperty 
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Xlib Function 


Protocol Request 


XSetDashes 


SetDashes 


XSetFillRule 


ChangeGC 


XSetFillStyle 


ChangeGC 


XSetFont 


ChangeGC 


XSetFontPath 


SetFontPath 


XSetForeground 


ChangeGC 


XSetFunction 


ChangeGC 


XSetGraphicsExposures 


ChangeGC 


XSetlconName 


ChangeProperty 

O At/ 


XSetlconSizes 


ChangeProperty 


XSetlnputFocus 


SetlnputFocus 


XSetLineAttributes 


ChangeGC 


XSetModifierMapping 


SetModifierMapping 


XSetNormalHints 


ChangeProperty 


XSetPlaneMask 


ChangeGC 


XSetPointerMapping 


SetPointerMapping 


XSetScreenSaver 


SetScreenSaver 


XSetSelectionOwner 


SetSelectionOwner 


XSetSizeHints 


ChangeProperty 


XSetStandardProperties 


ChangeProperty 


XSetState 


ChangeGC 


XSetStipple 


ChangeGC 


XSetSubwindowMode 


ChangeGC 


XSetTile 


ChangeGC 


XSetTSOrigin 


ChangeGC 


XSetWMHints 


ChangeProperty 


XSetWindowBackground 


ChangeWindowAttributes 


XSetWindowBackgroundPixmap 


ChangeWindowAttributes 


XSetWindowBorder 


ChangeWindowAttributes 


XSetWindowBorderPixmap 


ChangeWindowAttributes 


XSetWindowBorderWidth 


ConfigureWindow 


yvkXil V V iiiuu w v^uiurnuip 


^nangt^vY incipw/\iirioui^9 


XSetZoomHints 


ChangeProperty 


XStoreBuffer 


ChangeProperty 


XStoreBytes 


ChangeProperty 
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Xlib Function 



Protocol Request 



XStoreColor 

XStoreColors 

XStoreName 

XStoreNamedColor 

XSync 

XTranslateCoordinates 

XUndefineCursor 

XUngrabButton 

XUngrabKey 

XUngrabKeyboard 

XUngrabPointer 

XUngrabServer 

XUninstallColormap 

XUnloadFont 

XUnmapSubwindows 

XUnmapWindow 

XWarpPointer 



StoreColors 

StoreColors 

ChangeProperty 

StoreNamedColor 

GetlnputFocus 

TranslateCoordinates 

ChangeWindow Attributes 

UngrabButton 

UngrabKey 

UngrabKeyboard 

UngrabPointer 

UngrabServer 

UninstallColormap 

QoseFont 

UnmapSubwindows 

UnmapWindow 

WarpPointer 



The following table lists each X protocol request (in alphabetical order) and the 
Xlib functions that reference it. 



Protocol Request 



Xlib Function 



AUocColor 

AUocColorCells 

AUocColorPlanes 

AUocNaniedColor 

AUowEvents 

Bell 

SetAccessControl 



ChangeActivePointerGrab 
SetQoseDownMode 



XAUocColor 

XAUocColorCells 

XAUocColorPlanes 

XAUocNamedColor 

XAUowEvents 

XBell 

XDisableAccessControl 

XEnableAccessControl 

XSetAccessControl 

XChangeActivePointerGrab 

XSetQoseDownMode 
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Protocol Request 



Xlib Function 



ChangeGC 



ChangeHosts 



ChangeKeyboardControl 



ChangeKeyboardMapping 

ChangePointerControl 

ChangeProperty 



XChangeGC 

XSetArcMode 

XSetBackground 

XSetQipMask 

XSetQipQrigin 

XSetPillRule 

XSetPillStyle 

XSetFont 

XSetForeground 

XSetFunction 

XSetGraphicsExposures 

XSetLineAttributes 

XSetPlaneMask 

XSetState 

XSetStipple 

XSetSubwindowMode 

XSetTile 

XSetTSOrigin 

XAddHost 

XAddHosts 

XRemoveHost 

XRemoveHosts 

XAutoRepeatOff 

XAutoRepeatOn 

XChangeKeyboardControl 

XChangeKeyboardMapping 

XChangePointerControl 

XChangeProperty 

XSetCommand 

XSetlconName 

XSetlconSizes 

XSetNormalHints 

XSetSizeHints 

XSetStandardProperties 

XSetWMHints 
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Protocol Request 



Xlib Function 



ChangeSaveSet 
ChangeWindowAttributes 



CirculateWindow 

Clear Area 
CloseFont 
ConfigureWindow 



ConvertSelection 
Copy Area 

CopyColormapAndFree 



XSetZoomHints 

XStoreBuffer 

XStoreBytes 

XStorcNanie 

XAddToSaveSet 

XChangeSaveSet 

XRemoveFromSaveSet 

XChangeWindowAttributes 

XDefineCursor 

XSelecflnput 

XSetWindowBackground 

XSetWindowBackgroundPixmap 

XSetWindowBorder 

XSetWindowBorderPixmap 

XSetWindowColormap 

XUndefineCursor 

XCirculateSubwindowsDown 

XCirculateSubwindowsUp 

XCirculateSubwindows 

XClearArea 

XClearWindow 

XFreeFont 

XUnloadFont 

XConfigureWindow 

XLowerWindow 

XMapRaised 

XMoveResizeWindow 

XMoveWindow 

XRaiseWindow 

XResizeWindow 

XRestackWindows 

XSetWindowBorderWidth 

XConvertSelection 

XCopyArea 

XCop5<k)lormapAndFree 
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Protocol Request 



Xlib Function 



CopyGC 

CopyPlane 

CreateColormap 

CreateCursor 

CreateGC 



CreateGlyphCursor 
CreatePixmap 

CreateWindow 

DeleteProperty 
DestroySubwindows 
DestroyWindow 
FillPoly 

ForceScreenSaver 



FreeColormap 
FreeColors 
FreeCursor 
FreeGC 



FreePixmap 
GetAtomName 
GetFontPath 
GetGeometry 



XCopyGC 

XCopyPlane 

XCreateColormap 

XCreatePbonapCursor 

XCreateGC 

XCreateBitmapFromData 

XCreatePixmapFromData 

XOpenDisplay 

XReadBitmapFile 

XCreateFontCursor 

XCreateGlyphCursor 

XCreatePixmap 

XCreateBitmapFromData 

XCreatePixmapFromData 

XReadBitmapFile 

XCreateSimpleWindow 

XCreateWindow 

XDdeteProperty 

XDestroySubwindows 

XDestroyWindow 

XFillPolygon 

XActivateScreenSaver 

XForceScreenSaver 

XResetScreenSaver 

XFreeColormap 

XFreeColors 

XFreeCursor 

XFreeGC 

XCreateBitmapFromData 

XCreatePixmapFromData 

XReadBitmapFile 

XFreePixmap 

XGetAtomName 

XGetFontPath 

XGetGeometry 
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Protocol Request 


Xlib Function 




Vr^pf Wi nHo w A f fri Vii i I-pq 




XGetlmaffe 


C^etlnoutFocus 


XGetlnDutFocus 






y LaJcu Uv^Ul 111 Ul 


Ynpf "K'pvhn;! rH Pon f rol 


^jeuveyix)arcijviappin.g 


yvvjd^cy uudrviivid ppi^^ ig 


\^eix>^OQineriviapping 


^\jit;iiviuviincriyidppiiig 




/VVJCIIVIU liV/i li^ V Cl Ltd 


GetPointerControl 


XGetPointerControl 


vjctl Ullllc^riVlappillg 


/VVJCIX \^IllldiyxdL/L/Iil^ 


Vjeu. roperty 






yFpfrViKr;imp 
yvjrciv.iu.>i dii ic 








XGetNormalHints 




XGetSizeHints 




yvvjic i V V iviri.ii iis 




YGpf ^A7i riHoiA/Pronprfv 

✓VvJClVVlllvlLfVVl l\JLA^Ity 




XGetZoomHints 


GetSelectionOwner 


XGetSelectionOwner 


GetWindowAttributes 


XGetWindow Attributes 


VJ I d U D U. I Ivli I 


XGrahRiiHnn 


GrahKpv 


XGrabKev 


Vjii aC/^v?y LHJdl vi. 


yGrahlCpvhnflrH 
yvvji dL/Jvcy LAJdi u 




XGra hPni nf pr 




XGrah^rvpr 
yvvjidL/ib^d vci 




YF)ra wTnna O'P^f H p"1 A 


ImageTextS 


XDrawImageString 


InstallCoIormap 


XInstallColormap 


IntemAtom 


XInternAtom 


KillQient 


XKillClient 


ListExtensions 


XListExtensions 


ListFonts 


XListFonts 


ListFontsWithlnfo 


XListFontsWitWnfo 


ListHosts 


XListHosts 


ListlnstalledColormaps 


XListlnstalledColormaps 
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Protocx)! Request 

ListProperties 
LookupColor 

MapSubwindows 
MapWindow 

NoOperation 
OpenFont 

PolyArc 

PolyFillArc 

PolyPillRectangle 

PolyLine 
PolyPoint 

PolyRectangle 

PolySegment 

PolyTextl6 

PolyTextS 

Putlmage 

QueryBestSize 

QueryColors 

A-12 
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XLisiProperties 

XLookupColor 

XParseColor 

XMapSubwindows 

XMapRaised 

XMapWindow 

XNoOp 

XLoadFont 

XLoadQueiyFont 

XDrawArc 

XDrawArcs 

XFillArc 

XFillArcs 

XFillRectangle 

XFillRectangles 

XDrawLines 

XDrawPoint 

XDrawPoints 

XDrawRectangle 

XDrawRectangles 

XDrawUne 

XDrawSegments 

XDrawStringl6 

XDrawTextl6 

XDrawString 

XDrawText 

XPutlmage 

XCreateBitmapFromData 

XCreatePixmapFromData 

XReadBitmapFile 

XQueryBestCursor 

XQueryBestSize 

XQueryBestStipple 

XQueryBestTile 

XQueryColor 
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Protocol Request 


Xlib Function 




XQueryColors 


QueryExtension 


XInitExtension 




XQueryExtension 


QueryFont 


XLoadQueryFont 




XQueryFont 


QueryKeymap 


XQueryKeymap 


OuervPointer 


XQueryPointer 


QueiyTextExtents 


XQueryTextExtents 




XQueryTextExtentsl6 


QueiyTree 


XQueryTree 


RecolorCursor 


XRecolorCursor 


ReparentWindow 


XReparentWindow 


RotateProperties 


XRotateBuffers 




XRotateWindowProperties 


SendEvent 


XSendEvent 


SetQipRectangles 


XSetQipRectangles 


SetQoseDownMode 


XSetQoseDownMode 


SetDashes 


XSetDashes 


SetFontPath 


XSetFontPath 


SetlnputFocus 


XSetlnDutFocus 


SetModifierMapping 


XSetModifierMapping 


SetPointerMapping 


XSetPointerMappine 


SetScreenSaver 


XGetScreenSaver 




XSetScreenSaver 


SetSelectionOwner 


XSetSelectionOwner 


StoreColors 


XStoreColor 




XStoreColors 


StoreNamedColor 


XStoreNamedColor 


TranslateCoordinates 


XTranslateCoordinates 


UngrabButton 


XUngrabButton 


UngrabKey 


XUngrabKey 


UngrabKeyboard 


XUngrabKeyboard 


UngrabPointer 


XUngrabPointer 


UngrabServer 


XUngrabServer 


UninstallColormap 


XUninstallColonnap 
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Protocol Request Xlib Function 



UnmapSubwindows XUnmapSubWindows 
UnmapWindow XUnmapWindow 
WarpPointer XWarpPointer 
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Xlib Font Cursors bT 

Introduction B-1 
Tabte of Contents i 



Xlib Font Cursors 



Introduction 

The following are the available cursors that can be used with XCreateFontCur- 
sor. 



Idefine 




Idafine 


XC 11 anale 76 


Idefine 


XC ATTOtt 2. 


Idafine 


XC Ir enala 78 


idafino 


IflC Tinimfl fow doun 4 


Idafine 


XC nan 80 


Idafine 


YP Ha waH Ajrrow ud 6 


Idefine 


XC micklltfsutton 82 


Idefine 


XC hoat 8 


Idefine 


XC mnniio 84 

JIM Ulk/U0V W^ 


Idefine 


XC boooeitv 10 


Idafine 


XC oendl 86 

JIM J^ptlMjh Jb W W 


Idefine 


XC hoi't'oin Ift^fr flOTTiAT* 12 


Idafine 


XC Dirattt 88 

JIM yXAtfW*^ WW 


Idefine 




Idefine 


XC nliifl 90 


Idefine 


XC bottom aide 16 


Idafine 


XC oiiAation annoir 92 


Idefine 


XC bottom tee 18 


Idafine 


XC ri<dit Dtr 94 


Idefine 


XC box soiral 20 


Idafine 


XC T±dtktL nidm 96 

JIM J» X%|1H# ^W 


Idefine 


XC csanter otr 22 


Idafine 


XC ridht tee 98 

JIM A. A^fMW^t* W ^W 


Idefine 


XC circle 24 


Idafine 


XC ridhtbutton 100 


Idefine 


XC clock 26 


Idafine 


XC rtl logo 102 


Idefine 


XC coffee mucf 28 


Idafine 


XC aailboat 104 


Idefine 


XCjcross 30 


Idefine 


XCjBbjdown_arroif 106 


Idefine 


XCjcro88_rever8e 32 


Idefine 


XCjBb_hjd0ublejarzow 108 


Idefine 


XCjcrosahair 34 


Idefine 


XC_ab_left_arrow 110 


Idefine 


XCjdiaiiiond_cro88 36 


Idefine 


XC_ab_ri^t_arrow 112 


Idefine 


XCjdot 38 


Idefine 


XC_abjppjarrow 114 


Idefine 


XCjdotJ:>oxjna8]c 40 


Idafine 


XC_ab_vjdouble_arrow 116 


Idefine 


XCjdoublejarrow 42 


Idafine 


XC_8huttle 118 


Idefine 


XCjdraft_large 44 


Idefine 


XC_8izing 120 


Idefine 


XCjdb:aft_small 46 


Idafine 


xq_spidar 122 


Idefine 


XCjdr«^J>ox 48 


Idefine 


XC_8praycan 124 


Idefine 


XCjBxchange 50 


Idefine 


XC_8tar 126 


Idefine 


XC_f leur 52 


Idefine 


XCJbazget 128 


Idefine 


XCjgobbler 54 


Idefine 


XCJbcro88 130 


Idefine 


XCjguzd^y 56 


Idefine 


XCJtop_leftjM:row 132 



Xlib Font Cursors 



B-1 



Xllb Font Cursors 



fdaf ine XCJiand 58 
«dftf ine XCJiandljnaak 60 
#def ine XCJieart 62 
Idef ine XC_ioon 64 
#def ine XC_ironjoross 66 
«Gbf ine XC_leftjptr 68 
tdefine XC_le£t_eide 70 
«def ina XC^UftJtM 72 
tdefine XC l^ftbutton 74 



tdefine XCJbopJL^ftjPomer 134 
tdefine XCJkopjtlghtjesoiMr 136 
tdefine XCJtop_sid» 138 
tdefine XCJbopJbM 140 
tdefine XCJbx^ 142 
tdefine XCjil^angle 144 
tdefine XCjinbralU 146 
tdefine XCjarwigU 148 
tdefine XCjMatch 150 
tdefine XC xtem 152 
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Introduction 

Because X can evolve by extensions to the core protocol, it is important that 
extensions not be perceived as second class citizens. At some point, your favor- 
ite extensions may be adopted as additional parts of the X Standard. 

Therefore, there should be little to distinguish the use of an extension from that 
of the core protocol. To avoid having to initialize extensions explicitly in appli- 
cation programs, it is also important that extensions perform "lazy evaluations" 
and automatically initialize themselves when called for the first time. 

This appendix describes techniques for writing extensions to Xlib that will run 
at essentially the same performance as the core protocol requests. 



It is expected that a given extension to X consists of multiple requests. 
Defining ten new features as ten separate extensions is a bad practice. 
Rather, they should be packaged into a single extensbn and should use 
minor opcodes to distinguish the requests. 

The symbols and macros used for writing stubs to Xlib are listed in 
<X11/Xlibint.h >. 
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Basic Protocol Support Routines 



The basic protocol requests for extensions are XQueryExtension and XListEx- 
tensions. 

Bool IKQaKC^fExtension {display, name, majofjofcode jetum, fini jvenijetum, first 
Display *display; 
char *name; 

int *niajofjfpcodejetuTn; 
int *firstjventjetum) 
int *first_error_retum; 

XQueryExtension determines if the named extension is present If so, the major 
opcode for the extension is returned (if it has one); otherwise. False is returned. 
Any minor opcode and the request formats are specific to the extension. If the 
extension involves additional event types, the base event type code is returned; 
otherwise. False is returned. The format of the events is specific to the exten- 
sion. If the extension involves additional error codes, the base error code is 
returned; otherwise. False is returned. The format of additional data in the 
errors is specific to the extension. 

The extension name should be in the ISO Latin-1 encoding, and uppercase and 
lowercase do matter. 

char **XZ«i8tExtenaion8 (display, nextenskmsjretum) 
Display ^display; 
int *nextensionsjretum; 

XListExtensions returns a list of all extensions supported by the server. 

XFreeiExtensionLiBt (list) 
char **list; 

XFreeExtensionList frees the memory allocated by XListExtensions. 
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These functions allow you to hook into the library. They are not normally used 
by application programmers but are used by people who need to extend the 
core X protocol and the X library interface. The functions, which generate pro- 
tocol requests for X, are typically called stubs. 

In extensions, stubs first should check to see if they have initialized themselves 
on a connection. If they have not, they then should call XlnitExtension to 
attempt to initialize themselves on the connection. 

If the extension needs to be informed of GC/font allocation or deallocation or if 
the extension defines new event types, the functions described here allow the 
extension to be called when these events occur. 

The XExtCodes structure returns the information from XlnitExtension and is 
defined in 



<X11/Xlib.h>: 

typedef struct JXBxtCodes { /* public to extension, cannot be changed */ 

int extension; /* extension number */ 

int major_opcode; /* major op-code assigned by server */ 

int firstjevent; /* first event nunober £or the extension V 

int firstjerror; /* first error nunber for the extension */ 

} XExtCodes ; 



XExtCodes *XIzi±tZ}±eaaion (display, name) 
Display *display; 
char *mme; 

XlnitExtension determines if the extension exists. Then, it allocates storage for 
maintaining the information about the extension on the connection, chains this 
onto the extension list for the connection, and returns the information the stub 
implementor will need to access the extension. If the extension does not exist, 
XlnitExtension returns NULL. 

In particular, the extension number in the XExtCodes structure is needed in the 
other calls that follow. This extension number is unique only to a single connec- 
tion. 

XExtCodes *XAddExtension( (display) 
Display VtspZay; 
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For local Xlib extensions, XAddEKtension allocates the XExtCodes structure, 
bumps the extension number count, and chains the extension onto the extension 
list. (This permits extensions to Xlib without requiring server extensions.) 
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These functions allow you to define procedures that are to be called when vari- 
ous circun\stances occur. The procedures include the creation of a new GC for a 
connection, the copying of a GC, the freeing a GC, the creating and freeing of 
fonts, the conversion of events defined by extensions to and from wire format, 
and the handling of errors. 

All of these functions return the previous routine defined for this extension. 

int (*XESetClo8eDi8play(</is^2(iy/ extension, poc))() 
Display ^display; /* display */ 

int extension; /* extension number */ 
int (*jfroc)0; /* routine to call i^^en display dosed */ 

You use this procedure to define a procedure to be called whenever 
XCloseDisplay is called. This procedure returns any previously defined pro- 
cedure, usually NULL. 

When XCloseDisplay is called, your routine is called with these arguments: 

(*proc) (display, codes) 

Display ^display; 
XExtCodes "^codes; 

int (*XBSetCreateGC (display, extension, proc))0 
Display ^display; /* display */ 

int extension; /* extension number */ 
int (*proc)0; /* routine to call v/tien GC created ♦/ 

You use this procedure to define a procedure to be called whenever a new GC 
is created. This procedure returns any previously defined procedure, usually 
NULL. 

When a GC is created, your routine is called with these arguments: 

Cproc)(display, codes) 
Display ^display; 
GCgc; 

XExtCodes "^codes; 
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int ( *XESetCopyGC ( display, extension, poc))() 
Display ^display; /* display */ 

int extension) /* extension number */ 
int (*prDc)(); /* routine to call when GC copied */ 

You use this procedure to define a procedure to be called whenever a GC is 
copied. This procedure returns any previously defined procedure, usually 
NULL. 

When a GC is copied, your routine is called with these arguments: 

(*proc)(display, gc, codes) 
Display *display; 
GCgg 

XExtCodes *codes; 

int ( *XESet:Fr«ieGC ( display, extension, proc))0 
Display ^display; /* display */ 

int extension; extension number */ 
int (*proc)(); /* routine to call when GC freed */ 

You use this procedure to define a procedure to be called whenever a GC is 
freed. This procedure returns any previously defined procedure, usually NULL. 

When a GC is freed, your routine is called with these arguments: 

(*proc)(display, gc, codes) 
Display *display; 
GCgc; 

XExtCodes ''codes; 

int (*XESetCreateFont {display, extension, proc))0 
Display ^display; /* display */ 

int extension; /* extension number */ 
int (*proc)0; /* routine to call wheii font created */ 

You use this procedure to define a procedure to be called whenever XLoad- 
QueryFont and XQueryFont are called. This procedure returns any previously 
defined procedure, usually NULL. 

When XLoadQueryFont or XQueryFont is called, your routine is called with 
these arguments: 
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CprocXdisplay, fs, codes) 
Display ^display; 
XFontStruct ♦fs; 
XExtCodes »codes; 

int (*XBSetFreeFont {display, extension, proc))0 
Display * display; /* display */ 

int extension; /* extension number 
int (*prw:)(); /* routine to call i^en font freed */ 

You use this procedure to define a procedure to be called whenever XFreeFont 
is called. This procedure returns any previously defined procedure, usually 
NULL. 

When XFreeFont is called, your routine is called with these arguments: 

(*proc)(display, fs, codes) 
Display *display; 
)CFontStruct ♦fs; 
XExtCodes "codes; 

The next two functions allow you to define new events to the library. 





ii 







There is an implementatbn limit such that your host event structure size 
cannot be bigger than the size of the XEvent union of structures. There 
also is no way to guarantee that more than 24 elements or 96 characters in 
the structure will be fully portable between machines. 



int (*XBSetWireT6Bvent (display, event jiuniber, proc))() 
Display ^display; /* display */ 

int eventjtumher; /* event routine to replace */ 

Bool (*proc)0; /* routine to call wh&x converting event */ 

You use this procedure to define a procedure to be called when an event needs 
to be converted from wire format ( xEvent ) to host format ( XEvent ). The 
event number defines the protocol event number for which to install a conver- 
sion routine. This procedure returns any previously defined procedure. 
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You can replace a core event conversion routine witli one of your own, 
althougli tliis is not encouraged. It would, however, albw you to intercept a 
core event and modify it before being placed in the queue or otherwise 
examined. 

When Xlib needs to convert an event from wire format to host format your rou- 
tine is called with these ailments: 

Status CprocKdisplay, re, event) 
Display *display; 
XEvent *re; 
xEvent *event; 

Your routine must return status to indicate if the conversion succeeded. The re 
argument is a pointer to where the host format event should be stored, and the 
event argument is the 32-byte wire event structure. In the XEvent structure you 
are creating, type must be the first member and window must be the second 
member. You should fill in the type member with the type specified for the 
xEvent structure. You should copy all other members from the xEvent struc- 
ture (wire format) to the XEvent structure (host format). Your conversion rou- 
tine should return True if the event should be placed in the queue or False if it 
should not be placed in the queue. 

status (*XBSetEventToWire {display, eventjtumber, jmK))0 
Display ^display; /* display */ 

int event jiuniber; /* event routine to replace */ 

int {*proc)0; /* routine to call when converting event */ 

You use this procedure to define a procedure to be called when an event needs 
to be converted from host format ( XEvent ) to wire format ( xEvent ) form. 
The event number defines which protocol event number to install a conversion 
routine for. This procedure returns any previously defined procedure. It 
returns zero if the conversion fails or nonzero otherwise. 



NOTE 



You can replace a core event conversbn routine with one of your own, 
although this is not encouraged. It would, however, allow you to intercept a 
core event and modify it before being sent to another client. 



When Xlib needs to convert an event from wire format to host format, your rou- 
tine is called with these arguments: 
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(*proc)(display, re, event) 
Display ^display; 
XEvent *re; 
xEvent *event; 

The re argument is a pointer to the host format event, and the event argument 
is a pointer to where the 32-byte wire event structure should be stored. In the 
XEvent structure that you are forming, you must have "type" as the first 
member and "window" as the second. You then should fill in the type with the 
type from the xEvent structure. All other members then should be copied from 
the wire format to the XEvent structure. 

int ( *XESetError ( display, extension, proc))0 
EHsplay *display; /* display */ 

int extension; /* extension number */ 
int (*pwc)(); /* routine to call when X error happens */ 

Inside Xlib, there are times that you may want to suppress the calling of the 
external error handling when an error occurs. This allows status to be returned 
on a call at the cost of the call being synchronous (though nK)st such routines 
are query operations, in any case, and are typically programmed to be S5mchro- 
nous). 

When Xlib detects a protocol error in _XReply, it calls your procedure with 
these arguments: 

int (*proc)(display, err, codes, retjcode) 
Display *display; 
xError *err; 
XExtCodes ♦codes; 
int *retjcode; 

The err argument is a pointer to the 32-byte wire format error. The codes argu- 
ment is a pointer to the extension codes structure. The ret_code argument is the 
return code you may want _XReply returned to. 

If your routine returns a zero value, the error is not suppressed, and the client's 
error handler is called. (For further information, see **Using the Default Error 
Handlers" in Chapter 8) If your routine returns nonzero, the error is suppressed, 
and _XReply returns the value of retjcode. 
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char * (*XBStttErrorString ( display, extension, jnvcM) 
Display ^display; /♦ display •/ 

int extension; r extension number */ 
char *{*jfroc){y, /* routine to call to obtain an error string */ 

The XGetErrorText function returns a string to the user for an error. XESetEr- 
rorString allows you to define a routine to be called that should return a 
pointer to the error message. The following is an example. 

rproc)(display, code, codes, buffer, nbytes) 
Display ^display; 
int code; 

XExtCodes *codes; 
char *buffer; 
int nbytes; 

Your procedure is called with the error code for every error detected. You 
should copy nbytes of a null-terminated string containing the error message into 
buffer. 

int (*XBSetFlushGC (<{isplay, extension, proc))() 
Display *dispUiy; /* display */ 

int extension; /* extension number */ 
char *(*proc)(); /* routine to call when I/O error happens */ 

The XESetFlushGC procedure is identical to XESetCopyGC except that XESet- 
FlushGC is called when a GC cache needs to be updated in the server. 
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Various Xlib data structures have provisions for extension routines to chain 
extension supplied data onto a list. These structures are GC, Visual, Screen, 
ScreenForraat, Display, and XFontStruct. Because the list pointer is always 
the first member in the structure, a single set of routines can be used to manipu- 
late the data on these lists. 

The following structure is used in the routines in this section and is defined in < 
Xll/Xlib.h>: 



typedef struct JXBxtData ( 
int nunber; 

struct _XExtData *naxt; 
int (*frae) () ; 
char *private; 
} XBxtData; 



/* nunober returned by XInitExtension */ 
/* next item on list of data for structure */ 
/* if defined, called to free private */ 
/* data private to this extension. */ 



When any of the data structures listed above are freed, the list is walked, and 
the structure's free routine (if any) is called. If free is NULL, then the library 
frees both the data pointed to by the private member and the structure itself. 

union { Display *display; 
GC gc; 

Visual *visual; 
Screctti *screen; 
ScreeiiFomiat ^ixmap^format; 
XFontStruct *font ) XBDataObject; 

XBxtData **XEiieadOfExtensionList (object) 
XESDataObject object ; 

XEHeadOfExtensionList returns a pointer to the list of extension structures 
attached to the specified object. In concert with XAddToExtensionList, 
XEHeadOf ExtensionList allows an extension to attach arbitrary data to any of 
the structures of types contained in XEDataC^ject. 

XlkkiToExtensionList {structure, extjiata) 

struct _XExtData "^structure; pointor to structure to add 

XExtData ^extjkia; /* extensicm data structure to add 

The structure argument is a pointer to one of the data structures enumerated 
above. You must initialize ext_data->number with the extension number before 
calling this routine. 
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XExtData ^XE'inclOnExtensionListC structure, number) 
struct _XExtData **structure; 

int number; extension number from XInitExtension */ 

XFindOnExtensionList returns the first extension data structure for the exten- 
sion numbered number. It is expected that an extension will add at most one 
extension data structure to any single data structure's extension data list. There 
is no way to find additional structures. 

The XAllocID macro, which allocates and returns a resource ID, is defined in < 
Xll/Xlib.h>. 

X2U.10CID {display) 
Display ^display; 

This macro is a call through the Display structure to the internal resource ID 
allocator. It returns a resource ID that you can use when creating new 
resources. 
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GCs are cached by the library to allow merging of independent change requests 
to the same GC into single protocol requests. This is typically called a write- 
back cache. Any extension routine whose behavior depends on the contents of a 
GC must flush ihe GC cache to make sure the server has up-to-date contents in 
its GC. 

The FlushGC macro checks the dirty bits in the librar/s GC structure and calls 
_XFlushGCCache if any elements have changed. The FlushGC macro is defined 
as follows: 

FlushGC ( display, gc) 
Display ^display; 
GC gc; 

Note that if you extend the GC to add additional resource ID components, you 
should ensure that the library stub sends the change request immediately. This 
is because a client can free a resource inunediately after using it, so if you only 
stored the value in the cache without forcing a protocol request, the resource 
might be destroyed before being set into the GC. You can use the 
_XFlushGCCache procedure to force the cache to be flushed. The 
^XFlushGCCache procedure is defined as follows: 

jnPl u abGCCadbm {dispUn/, gc) 
Display ^display; 
GC gc; 
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If you extend X to add more poly graphics primitives, you may be able to take 
advantage of facilities in the library to allow back-to-back single calls to be 
transformed into poly requests. This may dramatically improve performance of 
programs that are not written using poly requests. A pointer to an xReq, called 
last^req in the display structure, is the last request being processed. By checking 
that the last request type, drawable, gc, and other options are the same as the 
new one and that there is enough space left in the buffer, you may be able to 
just extend the previous graphics request by extending the length field of the 
request and appending the data to the buffer. This can improve performance by 
five times or more in naive programs. For example, here is the source for the 
XDrawPoint stub. (Writing extension stubs is discussed in the next section.) 

#include <X11/Xlibint.h> 

/* precompute the maximum size of batching request allowed */ 

static int size = sizeof(xPolyPointReq) + EPERBATCH * sizeof(xPoint); 

XDrawPoint(dpy, d, gc, x, y) 
register Display *dpy; 
Drawable d; 
GCgc; 

int X, y; INT16 */ 

{ 

xPoint *point; 
LockDisplay(dpy); 
HushGC(dpy, gc); 
{ 

register xPolyPointReq *req = (xPolyPointReq *) dpy->last_req; 

/* if same as previous request, with same drawable, batch requests */ 

if( 

(req->reqType == XPolyPoint) 
&& (req->drawable == d) 
&& (req->gc == gc->gid) 
&& (req->coordMode == CoordModeOrigin) 
&& ((dpy->bufptr + sizeof (xPoint)) <= dpy->bufmax) 
&& (((diar *)dpy->bufptr - (char *)req) < size) ) { 

point = (xPoint *) dpy->bufptr; 

req->length + = sizeof (xPoint) » 2; 

dpy->bufptr += sizeof (xPoint); 
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} 

else { 

GetReqExtra(PolyPoint, 4, req); /* 1 point = 4 bytes ♦/ 
req->drawable = d; 
req->gc = gc->gid; 

req->coordMode = CoordModeOrigin; 

point = (xPoint *) (req + 1); 

} 

point->x = x; 
point->y = y; 
} 

UnlockDisplay(dpy); 
SyncHandleO; 

} 

To keep clients from generating very long requests that may monopolize the 
server, there is a symbol defined in < Xll/Xlibint . h > of EPERBATCH on the 
number of requests batched. Most of the performance benefit occurs in the first 
few merged requests. Note that FlushGC is called b^re picking up the value of 
last_req, because it may modify this field. 
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All X requests always contain the length of the request, expressed as a 16-bit 
quantity of 32 bits. This means that a single request can be no more than 256K 
bytes in length. Some servers may not support single requests of such a length. 
The value of dpy->max_request_size contains the maximum length as defined 
by the server implementation. For further information, see "X Window System 
Protocol". 
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The < XI 1 /Xproto.h > file contains three sets of definitions that are of interest 
to the stub implementor: request names, request structures, and reply structures. 

You need to generate a file equivalent to < Xll/34)roto.h > for your extension 
and need to include it in your stub routine. Each stub routine also must include 
<X11/Xlibint.h >. 

The identifiers are deliberately chosen in such a way that, if the request is called 
X_DoSomething, then its request structure is xDoSomethingReq, and its reply is 
xDoSomethingReply. The GetReq family of macros, defined in 
< Xll/Xlibint.h >, takes advantage of this naming scheme. 

For each X request, there is a definition in < Xll/Xproto.h > that looks similar 
to this: 

#define X^DoSomething 42 

In your extension header file, this will be a minor opcode, instead of a major 
opcode. 
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Every request contains an 8-bit major opcode and a 16-bit length field expressed 
in units of four hyies. Every request consists of four bytes of header (containing 
the niajor opcode, the length field, and a data byte) followed by zero or more 
additional bytes of data. The length field defines the total length of the request, 
including the header. The length field in a request must equal the minimum 
length required to contain the request. If the specified length is smaller or larger 
than the required length, the server should generate a BadLength error. 
Unused bytes in a request are not required to be zero. 

long XMaxRaqiaestSize (display) 
Display ^display; 

XMaxRequestSize returns the maximum request size (in 4-byte units) supported 
by the server. Single protocol requests to the server can be no longer than this 
size. Extensions should be designed in such a way that long protocol requests 
can be split up into smaller requests. The protocol guarantees the size to be no 
smaller than 4096 unit (16384 bytes). 

Major opcodes 128 through 255 are reserved for extensions. Extensions are 
intended to contain multiple requests, so extension requests typically have an 
additional minor opcode encoded in the "spare" data byte in the request 
header, but the placement and interpretation of this minor opcode as well as all 
other fields in extension requests are not defined by the core protocol. Every 
request is implicitly assigned a sequence number (starting with one) used in 
replies, errors, and events. 

To help but not cure portability problems to certain machines, the B16 and B32 
macros have been defined so ttiat they can become bitfield specifications on 
some machines. For example, on a Cray, these should be used for all 16-bit and 
32-bit quantities, as discussed below. 

Most protocol requests have a corresponding structure typedef in 
< Xll/Xproto.h >, which looks like: 
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typedef struct J[)oSoinethingReq { 
CARD8 reqtTypa; 
CiURDS someDatuia; 
CARD16 length B16; 



/* XJ>oSoiiiBthing V 

/* used differently in different requests */ 
/* total # of bytes in request, divided by 4 */ 



/* reqqest-specific data */ 

> xDoSonethingReq; 

If a core protocol request has a single 32-bit argument, you need not declare a 
request structure in your extension header file. Instead, such requests use 

< Xll/Xproto.h >'s xResourceReq structure. This structure is used for any 
request whose single argument is a Window, Pixinap, Drawable, GContext, 
Font, Cursor, Colontiap, Atom, or VisuallD. 

typedef struct _Besouro^Req { 

CARD8 reqType; /* the request type, e.g. X_DoSoinething */ 

BYTE pad; /* not used */ 

CARD16 length B16; /* 2 (- total # of bytes in request, divided by 4) */ 

CARD32 id B32; /* the Window, Drawable, Font, GContext, etc. */ 

> 3d<esourceReq; 

If convenient, you can do something similar in your extension header file. 

In both of these structures, the reqTj^ field identifies the type of the request 
(for example, X_MapWindow or X_CreatePixmap). The length field tells how 
long the request is in units of 4-byte longwords. This length includes both the 
request structure itself and any variable length data, such as strings or lists, that 
follow the request structure. Request structures come in different sizes, but all 
requests are padded to be multiples of four bytes long. 

A few protocol requests take no arguments at all. Instead, they use 

< Xll/Xproto.h >'s xReq structure, which contains only a reqType and a 
length (and a pad byte). 

If the protocol request requires a reply, then < Xll/}qproto.h > also contains a 
reply structure t5^pedefi 
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typMtef struct ^poScnttthing^Reply { 



BYIE type; 

BYTE someDatum; 

CARD16 secpjenoeMunber B16; 

CARD32 length B32; 



/* always XReply */ 

/* used differently in different requests */ 

/* # of requests sent so far V 

/* « of additional bytes, divided by 4 */ 



/* request-specific data */ 
} xDoSomethin^teply; 

Most of these reply structures are 32 bytes long. If there are not that many reply 
values, then they contain a sufficient number of pad fields to bring them up to 
32 bytes. The length field is the total number of bytes in the request minus 32, 
divided by 4. This length will be nonzero only if: 

■ The reply structure is followed by variable length data such as a list or 
string. 

■ The reply structure is longer than 32 bytes. 

Only GetWindowAttributes, QueryFont, QueryKeyinap, and GetKeyboardCon- 
trol have reply structures longer than 32 bytes in the core protocol. 

A few protocol requests return replies that contain no data. 

< Xll/Xproto.h > does not define reply structures for these. Instead, they use 
the xGenericReply structure, which contains only a type, length, and sequence 
number (and sufficient padding to make it 32 bytes long). 
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An Xlib stub routine should always start like this: 
#include "Xll/XlibinLh" 

XDoSomething (arguments, ... ) 
r argument declarations "^Z 
{ 

register XDoSomethingReq "^req; 

If the protocol request has a reply, then the variable declarations should include 
the reply structure for the request. The following is an example: 

xDoSomethingReply rep; 
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Locking Data Structures 



To lock the display structure for ^sterns that want to support multithreaded 
access to a single display connection, each stub will need to lock its critical sec- 
tion. Generally, this section is the point from just before the appropriate GetReq 
call until all arguments to the call have been stored into the buffer. The precise 
instructions needed for this locking depend upon the machine architecture. Two 
calls, which are generally implemented as macros, have been provided. 

LockDisplay ( display) 
Display *display, 

UnlockDisplay (display) 
Display ^display; 
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Sending the Protocol Request and Arguments 



After the variable declarations, a stub routine should call one of four macros 
defined in < Xll/Xlibint . h >: GetReq, GetReqExtra, GetResReq, or GetEnp- 
tyReq. All of these macros take, as their first argument, the name of the proto- 
col request as declared in < Xll/Xproto.h > except with X_ removed. Each one 
declares a Display structure pointer, called dpy, and a pointer to a request 
structure, called req, which is of the appropriate type. The macro then appends 
the request structure to the output buffer, fills in its type and length field, and 
sets req to point to it. 

If the protocol request has no arguments (for instance, X GrabServer), then use 
GetEniptyReq. 

GetEmptyReq (DoSomeflimg); 

If the protocol request has a single 32-bit argument (such as a Pixinap, Window, 
Drawci)le, Atom, and so on), then use GetResReq. The second argument to the 
macro is the 32-bit object. XjlapWindow is a good example. 

GetResReq (DoSomething, rid); 

The rid argument is the Pixinap, Window, or other resource ID. 

If the protocol request takes any other argument list, then call GetReq. After 
the GetReq, you need to set all the other fields in the request structure, usually 
from arguments to the stub routine. 

GetReq (DoSomething); 
/"^ fill in arguments here *l 
req->argl = argl; 
req->arg2 = arg2; 

A few Stub routines (such as XCreateGC and XCreatePixmap) return a resource 
ID to the caller but pass a resource ID as an argument to the protocol request. 
Such routines use the macro XAllocID to allocate a resource ID from the range 
of IDs that were assigned to this client when it opened the connection. 

rid = req->rid = XAUocIDO; 
return (rid); 

Finally, some stub routines transmit a fixed amount of variable length data after 
the request. Typically, these routines (such as XMoveWindow and XSetBack- 
ground) are special cases of more general functions like 
XMoveResizeWindow and XChangeGC. These special case routines use 
GetReqExtra, which is the same as GetReq except that it takes an additional 
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argument (the number of extra bytes to allocate in the output buffer after the 
request structure). This number should always be a multiple of four. 
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Variable Length Arguments 



Some protocol requests take additional variable length data that follow the xDo- 
SoroethingReq structure. The format of this data varies from request to request. 
Some requests require a sequence of 8-bit bytes, others a sequence of 16-bit or 
32-bit entities, and still others a sequence of structures. 

It is necessary to add the length of any variable length data to the length field of 
the request structure. That length field is in units of 32-bit longwords. If the 
data is a string or other sequence of 8-bit bytes, then you must round the length 
up and shift it before adding: 

req->length += (nbytes+3)»2; 

To transmit variable length data, use the Data macros. If the data fits into the 
output buffer, then this macro copies it to the buffer. If it does not fit, however, 
the Data macro calls _XSend, which transmits first the contents of the buffer 
and then your data. The Data macros take three arguments: the Display, a 
pointer to the beginning of the data, and the number of bytes to be sent. 

Dat&idisplmf, (char *) data, nin/tes); 

Datal6(displm/, (short *) data, ribytes); 

DsLta32{display, (long *) data, ribytes); 

Data, Datal6, and Data32 are macros that may use their last argument more 
than once, so that argument should be a variable rather than an expression such 
as "nitems*sizeof(item)". You should do that kind of computation in a separate 
statement before calling them. Use the appropriate macro when sending byte, 
short, or long data. 

If the protocol request requires a reply, then call the procedure _XSend instead 
of the Data macro. _XSend takes the same arguments, but because it sends your 
data immediately instead of copying it into the output buffer (which would later 
be flushed anyway by the following call on _XReply), it is faster. 
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Replies 



If fhe protocol request has a reply, then call _XReply after you have finished 
dealing with all fhe fixed and variable length arguments. JKReply flushes the 
output buffer and waits for an xReply packet to arrive. If any events arrive in 
the meantime, _XReply places them in the queue for later use. 

status JCRitpIy(i<tsp2ay; rep, extra, discard) 
Display *dispUnf; 
xReply *f«p; 

int extru; /* number of 32-bit words expected after the reply */ 
Bool discard; /* should I discard data fdlowing "extra" words? */ 

JCReply waits for a reply packet and copies its contents into the specified rep. 
_XReply handles error and event packets that occur before the reply is received. 
JCReply takes four arguments: 

■ A Display * structure 

■ A pointer to a reply structure (which must be cast to an xReply *) 

■ The number of additional bytes (beyond sizeof( xReply ) = 32 b}^es) in 
the reply structure 

■ A Boolean that indicates whether JCReply is to discard any additional 
bytes beyond those it was told to read 

Because most reply structures are 32 bytes long, the third argument is usually 0. 
The only core protocol exceptions are the replies to GetWindowAttributes, 
QueryFont, QueryKeyinap, and GetKeyboardControl, which have longer 
replies. 

The last argument should be False if the reply structure is followed by addi- 
tional variable length data (such as a list or string). It should be True if there is 
not any variable length data. 



This last argument is provided for upward-compatibility reasons to allow a 
client to communicate properly with a hypothetical later version of the sender 
that sends more data than the client expected. For example, some later ver- 
sion of GetWindowAttributes might use a larger, but compatible, xGetwin- 
' dowAttributesReply that contains additional attribute data at the end. 

JCReply returns True if it received a reply successfully or False if it received 
any sort of error. 
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For a request with a reply that is not followed by variable length data, you 
write something like: 

_XReply(display, (xReply *)&rep, 0, True); 

*retl = repjetl; 

*ret2 = rep.ret2; 

»ret3 = rep.ret3; 

UnlockDisplayCdpy); 

SyncHandleO; 

return (rep.ret4); 

} 

If there is variable length data after the reply, change the True to False, and 
use the appropriate JXRead function to read the variable length data. 

JXBBadi display, data, nbytes) 
Display *disphnf; 
char *data; 
long nbytes; 

_XRead reads the specified number of b5^es into data. 

JISBBadlS (display, data, nbytes) 
Display ^display; 
short *data; 
long nbytes; 

_XReadl6 reads the specified number of bytes, unpacking them as 16-bit quani- 
ties, into the specified array as shorts. 

JSBBad32 (display, data, nbytes) 
Display ^display; 
long *data; 
long nbytes; 

_XRead32 reads the specified number of bytes, unpacking them as 32-bit quani- 
ties, into the specified array as longs. 

_XE<eadl6Pad( display, data, nbytes) 
Display * display; 
short ^data; 
long nbytes; 
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JKReadl6Pad reads the specified number of bytes, unpacking them as 16-bit 
quanities, into the specified array as shorts. If the number of bytes is not a mul- 
tiple of four, jKReadl6Pad reads up to three additional pad bytes. 

JXBBadBadidisplm/, data, nbytes) 
Display ^display; 
char *data; 
long ritifies; 

_XReadPad reads the specified number of bytes into data. If the number of 
bytes is not a multiple of four, _XReadPad reads up to three additional pad 
bytes. 

Each protocol request is a little different. For further information, see the Xlib 
sources for examples. 
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Synchronous Calling 

To ease debugging, each routine should have a call, just before returning to the 
user, to a routine called SyncHandle. This routine generally is implemented as 
a macro. If synchronous mode is enabled (see XSynchronize), the request is 
sent immediately. The library, however, waits until any error the routine could 
generate at the server has been handled. 
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Allocating and Deallocating Memory 

To support the possible reentry of these routines, you must observe several con- 
ventions when allocating and deallocating memory, most often done when 
returning data to the user from the window system of a size the caller could not 
know in advance (for example, a list of fonts or a list of extensions). The stan- 
dard C library routines on many systems are not protected against signals or 
other multithreaded uses. The following analogies to standard I/O library rou- 
tines have been defined: 

XmallocO Replaces mallocO 

XfreeO Replaces freeO 

XcallocO Replaces callocO 

These should be used in place of any calls you would make to the normal C 
library routines. 

If you need a single scratch buffer inside a critical section (for example, to pack 
and unpack data to and from the wire protocol), the general memory allocators 
may be too expensive to use (particularly in output routines, which are perfor- 
mance critical). The routine below returns a scratch buffer for your use: 

cheu: *^XkLlocScratdti {display, ribytes) 
Display ^display; 
unsigned long hbytes; 

This storage must only be used inside of the critical section of your stub. 
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Many machine architectures, including many of the more recent RISC architec- 
tures, do not correctly access data at unaligned locations; their compilers pad 
out structures to preserve this characteristic. Many other machines capable of 
unaligned references pad inside of structures as well to preserve alignment, 
because accessing aligned data is usually much faster. Because the library and 
the server use structures to access data at arbitrary points in a byte stream, all 
data in request and reply packets must be naturally aligned; that is, 16-bit data 
starts on 16-bit boundaries in the request and 32-bit data on 32-bit boundaries. 
All requests must be a multiple of 32 bits in length to preserve the natural align- 
ment in the data stream. You must pad structures out to 32-bit boundaries. 
Pad information does not have to be zeroed unless you want to preserve such 
fields for future use in your protocol requests. Floating point varies radically 
between machines and should be avoided completely if at all possible. 

This code may run on machines with 16-bit ints. So, if any integer argument, 
variable, or return value either can take only nonnegative values or is declared 
as a CARD16 in the protocol, be sure to declare it as unsigned int and not as int. 
(This, of course, does not apply to Booleans or enumerations.) 

Similarly, if any integer argument or return value is declared CARD32 in the 
protocol, declare it as an unsigned long and not as int or long. This also goes 
for any internal variables that may take on values larger than the maximum 16- 
bit unsigned int. 

The library currently assumes that a char is 8 bits, a short is 16 bits, an int is 16 
or 32 bits, and a long is 32 bits. The PackData macro is a half-hearted attempt 
to deal with the possibility of 32 bit shorts. However, much more work is 
needed to make this work properly. 
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The remaining problem a writer of an extension stub routine faces that the core 
protocol does not face is to map from the call to the proper major and minor 
opcodes. While there are a nurnber of strategies, the simplest and fastest is out- 
lined below. 

1. Declare an array of pointers, _NFILE long (this is normally found in 

< stdio.h > and is the number of file descriptors supported on the sys- 
tem) of type XExtCodes. Make sure these are all initialized to NULL. 

2. When your stub is entered, your initialization test is just to use the 
display pointer passed in to access the file descriptor and an index into 
the array. If the entry is NULL, then this is the first time you are enter- 
ing the routine for this display. Call your initialization routine and pass 
it to the display pointer. 

3. Once in your initialization routine, call XInitExtension; if it succeeds, 
store the pointer retumed into this array. Make sure to establish a close 
display handler to allow you to zero the entry. Do whatever other ini- 
tialization your extension requires. (For example, install event handlers 
and so on). Your initialization routine would normally return a pointer 
to the XExtCodes structure for this extension, which is what would nor- 
mally be found in your array of pointers. 

4. After returning from your initialization routine, the stub can now con- 
tinue normally, because it has its major opcode safely in its hand in the 
XExtCodes structure. 
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Drawing and Filling Polygons and Curves 



Xlib provides functions that you can use to draw or fill arbitrary polygons or 
curves. These functions are provided mainly for compatibility witfi XIO and 
have no server support. That is, they call oiher Xlib functions, not the server 
directly. Thus, if you just have straight Unes to draw, using XDrawLines or 
XDrawSegments is much faster. 

The functions discussed here provide all the functionality of the XIO functions 
XDraw, XDrawFilled, XDrawPatterned, XDrawDashed, and XDrawTiled. They 
are as compatible as possible given Xll's new line drawing functions. One thing 
to note, however, is tiiat VertexDrawLastPoint is no longer supported. Also, 
the error status returned is the opposite of what it was under XIO (this is the 
XI 1 standard error status). X/^pendVertex and XClearVertexFlag from XIO 
also are not supported. 

Just how the graphics context you use is set up actually detennines whether you 
get dashes or not, and so on. Lines are properly joined if they connect and 
include the closing of a closed figure (see XDrawLines). The functions dis- 
cussed here fail (return zero) only if they run out of memory or are passed a 
Vertex list that has a Vertex with VertexStartClosed set that is not followed 
by a Vertex with VertexEndClosed set. 

To achieve the effects of the XIO XDraw, XDrawDashed, and XDrawPatterned, 
use XDraw. 

finclude <X11/X10.h> 
Status XDrdM {display, d, gc, vlist, vcount) 
Display ^display; 
Drawable d; 
GCgc; 
Vertex *vlist; 
int vcount; 

Specifies the connection to the XwiN server. 
Specifies the drawable. 
Specifies the GC. 

Specifies a pointer to the hst of vertices that indicate what to draw. 
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vcount Specifies how many vertices are in vlist. 

XDraw draws an arbitrary polygon or curve. The figure drawn is defined by the 
specified list of vertices (vlist). The points are connected by lines as specified in 
the flags in the vertex structure. 

Each Vertex, as defined in < Xll/XlO .h >, is a structure with the following 
members: 

typedef struct ^ysrtex ( 
abort x,y; 

unsignod short flags; 
} Vertex; 

The X and y members are the coordinates of the vertex that are relative to either 
the upper-left inside comer of the drawable (if VertexRelative is zero) or the 
previous vertex (if VertexRelative is one). 

The flags, as defined in < Xll/XlO .h >, are as follows: 



VertexRelative 


0x0001 


/* 


else 


absolute */ 


VertexDontDraw 


0x0002 


/* 


else 


draw */ 


VertexCurved 


0x0004 


/* 


else 


straight */ 


VertexStartClosed 


0x0008 


/* 


else 


not V 


VertexEndClosed 


0x0010 


/* 


else 


not V 



■ If VertexRelative is not set, the coordinates are absolute (that is, relative 
to the drawable's origin). The first vertex must be an absolute vertex. 

■ If VertexDontDraw is one, no line or curve is drawn from the previous 
vertex to this one. This is analogous to picking up the pen and moving to 
another place before drawing another line. 

■ If VertexCurved is one, a spline algorithm is used to draw a smooth 
curve from the previous vertex through this one to the next vertex. Other- 
wise, a straight line is drawn from the previous vertex to this one. It 
makes sense to set VertexCurved to one only if a previous and next ver- 
tex are both defined (either explicifly in the array or through the 
definition of a dosed curve). 
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■ It is pemrdssible for VertexDontDraw bits and VertexCurved bits both to 
be one. This is useful if you want to define the previous point for the 
smooth curve but do not want an actual curve drawing to start until this 
point. 

■ If VertexStartClosed is one, then this point marks the beginning of a 
closed curve. This vertex must be followed later in the array by another 
vertex whose effective coordinates are identical and that has a VertexEnd- 
Closed bit of one. The points in between form a cycle to determine 
predecessor and successor vertices for the spline algorithm. 

This function uses these GC components: function, plane-mask, line-width, line- 
style, cap-style, join-style, fill-style, subwindow-mode, clip-x-origin, clip-y-origin, 
and clip-mask. It also uses these GC mode-dependent components: foreground, 
background, tile, stipple, tile-stipple-x-origin, tile-stipple-y-origin, dash-offset, 
and dash-list. 

To achieve the effects of the XIO XDrawTiled and XDrawFilled, use 
XDrawFilled. 



iincludtt <X11/X10.h> 

Status XDrsaiFillwUdisplaif, d, gc, vlist, vcount) 





Display ^display; 




Drawable d; 




GC gc; 




Vertex *vlist; 




int vcount; 


display 


Specifies the connection to the XwiN server. 


d 


Specifies the drawable. 




Specifies the GC. 


vlist 


Specifies a pointer to the list of vertices that indicate what to draw. 


vcount 


Specifies how many vertices are in vlist. 



XDrawFilled draws arbitrary polygons or curves and then fills them. 

This function uses these GC components: function, plane-mask, line-width, line- 
style, cap-style, join-style, fill-style, subwindow-mode, clip-x-origin, clip-y-origin, 
and clip-mask. It also uses these GC mode-dependent components: foreground, 
background, tile, stipple, tile-stipple-x-origin, tile-stipple-y-origin, dash-offset, 
dash-list, fill-style, and fill-rule. 
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These functions have been superseded by the context management functions 
(see "Using the Context Manager" in Oiapter 10). It is often necessary to associ- 
ate arbitrary information with resource IDs. Xlib provides the XAssocTable 
functions that you can use to make such an association. AppUcation programs 
often need to be able to easily refer to Iheir own data structures when an event 
arrives. The XAssocTable system provides users of the X library with a 
method for associating their own data structures with X resources ( Pixmaps , 
Fonts, Windows, and so on). 

An XAssocTable can be used to type X resources. For example, the user may 
want to have three or four types of windows, each with different properties. 
This can be accomplished by associating each X window ID with a pointer to a 
window property data structure defined by the user. A generic type has been 
defined in the X library for resource IDs. It is called an XID. 

There are a few guidelines that should be observed when using an 
XAssocTable: 

■ All XIDs are relative to the specified display. 

■ Because of the hashing scheme used by the association mechanism, the 
following rules for determining the size of a XAssocTable should be fol- 
lowed. Associations will be made and looked up more efficiently if 
the table size (number of buckets in the hashing system) is a power of 
two and if there are not more than 8 XIDs per bucket. 

To return a pointer to a new XAssocTable, use JffilreateAssocTable. 

X2Vs80cTable ^XCreateAssocTable (siz?) 
int size; 

size Specifies the number of buckets in the hash system of XAssocTable. 

The size argument specifies the number of buckets in the hash system of XAs- 
socTable. For reasons of efficiency the ntimber of buckets should be a 
power of two. Some size suggestions might be: use 32 buckets per 100 
objects, and a reasonable maximum number of objects per buckets is 8. If an 
error allocating memory for the XAssocTable occiu^, a NULL pointer is 
returned. 
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To create an entry in a given XAssocTable, use XMakeAssoc. 

XMakeAflSoc (display, table, xjd, data) 
Display *display; 
XAssocTable "^tabU; 
XID xjd; 
char *data; 

display Specifies the connection to the XwiN server. 
table Specifies the assoc table. 
xjd Specifies the X resource ID. 

data Specifies the data to be associated with the X resource ID. 

XMakeAssoc inserts data into an X2^socTable keyed on an XID. Data is 
inserted into the table only once. Redundant inserts are ignored. The queue in 
each association bucket is sorted from the lowest XID to the highest XID. 

To obtain data from a given XAssocTable, use XLookUpAssoc. 

char *XLo6k.VpAaaoc{displa:y, table, xjd) 
Display *display; 
XAssocTable *taible; 
XLDxJd; 

display Specifies the connection to the XwiN server. 
table Specifies the assoc table. 
xjd Specifies the X resource ID. 

XLookUpAssoc retrieves the data stored in an XAssocTable by its XID. If an 
appropriately matching XID can be found in the table, XLookUpAssoc returns 
the data associated with it. If the xjd cannot be found in the table, it returns 
NULL. 

To delete an entry from a given XAssocTable, use XDeleteAssoc. 

XDeletttAssoo ( display, table, xjd) 
Display ^display; 
XAssocTable *tiible; 
XLDxJd; 
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display Spedfies the connection to the XWIN server. 
table Spedfies the assoc table. 
xjd Spedfies the X resource ID. 

XDeleteAssoc deletes an association in an XAssocTable keyed on its XID. 
Redundant deletes (and deletes of nonexistent XIDs) are ignored. Deleting asso- 
ciations in no way impairs the performance of an XAssocTable. 

To free the memory assodated with a given XAssocTable, use XDestroyAs- 
socTable. 

XDestroyAssocTable ( table) 
XAssocTable *table; 

table Spedfies the assoc table. 
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Preface 



This is an extension to the XI 1 server and Xlib that provides two capabilities: 

■ It allows a client to generate user input actions in the server without 
requiring a user to be present. 

■ It also allows a client to control the handling of user input actions by the 
server. 

The capability to allow a client to generate user input actions in the server will 
be used by some of the X Testing Consortium Xlib tests. Both capabilities will 
be used by the X Testing Consortium client exerciser program. TTiese capabili- 
ties may also be useful in other programs. 

This extension requires modification to device-dependent code in the server. 
Therefore it is not a 'portable' extension as defined by the Xll Server Extensions 
document. However, the majority of the code and functionality of this exten- 
sion will be implementation-independent. 
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Conventions Used In This Document 



The naming conventions used in the Xlib documentation are followed with these 
additions: 

■ The names of all functions defined in this extension begin with OCTesf , 
with the first letter of each additional word capitalized. 

■ The names of the protocol request structiu^s follow the Xlib convention of 
'x<name>Req'. 

■ The names of the protocol request minor type codes follow the Xlib con- 
vention of 'X_<name>'. 

■ The names of all other constants defined in this extension begin with 
'XTesf , with the rest of the name in upper case letters. 

■ All constants and structures defined in this extension will have their 
values specified in the 'xtestextLh' file at the end of this document. 
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Input Actions 

Input actions are pointer movements, button presses and releases, and key 
presses and releases. They can be generated by a user or by a client (using 
functions in this extension). 



User Input Actions 

User input actions are input actions that are generated by the user moving a 
pointing device (typically a mouse), pressing and releasing buttons on the point- 
ing device, and pressing and releasing keys on the keyboard. 
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What Does This Extension Do? 



Without this extension, user input actions are processed by the server, and are 
converted into normal X events that are sent to the appropriate client or clients. 

This extension adds the following capabilities: 

■ Input actions may be sent from a client to the server to be processed just 
as if the user had physically performed them. The input actions are pro- 
vided to the server in the form of X protocol requests defined by this 
extension. The iirformation provided to the server includes what action 
should be performed, and how long to delay before processing the action 
in the server. 

■ User input actions may be diverted to a client before being processed by 
the server. The effect on the server is as if the user had performed no 
input action. The user input actions are provided to the client in the form 
of X events defined by this extension. The information provided to the 
client includes what user input action occurred and the delay between this 
user input action and the previous user input action. The client may then 
do anything it wishes with this information. 

■ User input actions may be copied, with one copy going to the server in 
the normal way, and the other copy being sent to a client as described 
above. 
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AT&T Enhancements to this Extension 

This section describes two additional Xlib calls added by AT&T Bell Labora- 
tories to allow the testing of clients that "grab" the server. These two calls 
prevent deadlock. Without these calls to encapsulate the simulated input, it 
would be possible for the client that "grabbed" the server and the client simulat- 
ing the input to both deadlock. Take for example, a window manager that 
"grabs" the server while resizing a window. When the window manager 
"grabs" the server, the server will ignore all events from other clients, including 
the client simulating the input. If tihe simulated button release to finish resizing 
the window is not already in the server's Input Synthesis Extension input 
buffer, the server will subsequently ignore the event containing the button 
release. The final result will be a deadlock; the window manager will be 
deadlocked waiting for a button release that will never come and the client 
simulating input will be deadlocked waiting for the server to send an ack- 
nowledgement that will never come. 

By calling XTestStartSimulation before sending simulated input, the server will 
continue accepting events from the calling client even if another client should 
"grab" the server. 

int 

XTestStartSimulation ( display ) 
Display ^display; 

display Specifies the connection to the X server. 

The XTestStartSimulation function must be called before any simulated input is 
sent to the server. If it is not called, the server will refuse all simulated input 
Once called and accepted, only the dient making the request will be able to 
simulate input. If any other client attempts to simulate input or calls XTestSimu- 
latelnput, its request will be refused. 

The XTestStartSimulation function will return -1 if there is an error or the request 
is denied, and 0 otherwise. 
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int 

XTestStopSimulation( display) 
Display ^display; 

display Specifies the connection to the X server. 

The XTestStopSitnulation function should be called after the client has finished 
simulating input. Once called, other clients will be able to call XTestStartSimula- 
tion. If a client fails to call XTestStopSimulation, other clients attempting to call 
XTestStartSimulation will be denied until the original client terminates. 

The XTestStopSimulation function will return -1 if there is an error, and 0 other- 
wise. 



High Level Functions 

These functions are built on top of the low level functions described later, 
int 

XTestMovePointer (display, device Jd, delay, x, y, count) 
Display ^display; 
int device Jd; 
unsigned long delayU; 
int 41; 
int y[l; 

unsigned int count; 
display Specifies the connection to the X server. 

device Jd Specifies which pointer device was supposed to have caused the 

input action. This is a provision for future support of multiple (dis- 
tinguishable) pointer devices,^d should always be set to 0 for 
now. 

delay Specifies the time (in milliseconds) to wait before each movement 

of the pointer. 

X 

y Specifies the x and y coordinates to move the pointer to relative to 

the root window for the specified display. 
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count Specifies the number of 'delay, x, y triplets contained in the delay, x 

and y arrays. 

The XTestMovePointer function creates input actions to be sent to the the server. 
The input actions will be accumulated in a request defined by this extension 
until the request is full or the XTestFlush function is called. They will then be 
sent to the server. When the input actions are sent to the server, the input 
actions will cause the server to think that the pointer was moved to the 
specified position(s), with the specified delay before each input action. 

The XTestMovePointer function will return -1 if there is an error, and 0 other- 
wise. 



XTestPressButton 

int 

XTestPressButton (display, device Jd, delay, button jiumher, 
button_action) 
Display *display; 
int device Jd; 
unsigned long delay; 
unsigned int buttonjiumber; 
unsigned int button action; 



display Specifies the connection to the X server. 

device Jd Specifies which button device was supposed to have caused 

the input action. This is a provision for future support of mul- 
tiple (distinguishable) button devices, and should always be set 
to 0 for now. 

delay Specifies the time (in milliseconds) to wait before the input 

action. 

buttonjiumber Specifies which button is being acted upon. 

button_action Specifies the action to be performed (one of XTestPRESS, 
XTestRELEASE, or XTestSTROKE). 

The XTestPressButton function creates input actions to be sent to the the server. 
The input actions will be accumulated in a request defined by this extension 
until the request is full or the XTestFlush function is called. They will then be 
sent to the server. When the input actions are sent to the server, the input 



X1 1 Input Synthesis Extension 



E-7 



Functions In This Extension 



actions will cause the server to think that the specified button was moved as 
specified. 

The XTestPressButton function will return -1 if there is an error, and 0 otherwise. 

XTestPressKey 

int 

XTestPressKey (display, device Jd, delay, keycode, keyjiction) 
Display ^display; 
int device Jd; 
unsigned long delay; 
unsigned int keycode; 
unsigned int keyjiction; 

Specifies the connection to the X server. 

Specifies which keyboard device was supposed to have caused the 
input action. This is a provision for future support of multiple (dis- 
tinguishable) keyboard devices, and should always be set to 0 for 
now. 

Specifies the time (in milliseconds) to wait before the input action. 

Specifies which keycode is being acted upon. 

Specifies the action to be performed (one of XTestPRESS, 
XTestRELEASE, or XTestSTROKE). 

The XTestPressKey function creates input actions to be sent to the the server. 
The input actions will be accumulated in a request defined by this extension 
until the request is full or the XTestFlush function is called. They will then be 
sent to the server. When the input actions are sent to the server, the input 
actions will cause the server to think that the specified key on the keyboard was 
moved as specified. 

The XTestPressKey function will return -1 if there is an error, and 0 otherwise. 



display 
devicejd 

delay 

keycode 

keyjiction 
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XTestFlush 

int 

XTestFlush (display) 
Display ^display; 

display Specifies the connection to the X server. 

The XTestFlush will send any remaining input actions to the server. 

The XTestFlush function will return -1 if there is an error, and 0 otherwise. 



Low Level Functions 
XTestGetlnput 

int 

XTestGetlnput (display, action Jiandling) 
Display ^display; 
int action Jiandling; 

display Specifies the connection to the X server. 

actionjiandling Specifies to the server what to do with the user input actions, 
(one of 0, XTestPACKEDJAOTION or 
XTestPACKEDj\CTIONS; optionally 'or'ed with 
XTestEXCLUSIVE). 

The XTestGetlnput function tells the server to begin putting information about 
user input actions into events to be sent to the client that called this function. 
These events can be read via the Xlib XNextEvent function. 

The server assigns an event type of XTestlnputActwnType to these events to dis- 
tinguish them from other events. Since the actual value of the event type may 
vary depending on how many extensions are included with an XI 1 implementa- 
tion, XTestlnputActionType is a variable that will be contained in the Xlib part of 
this extension. It may be referenced as follows: 

extern int XTestlnputActionType; 
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An actionjiandling value of 0 causes the server to send one user input action in 
each XTestlnputActionType event. This can sometimes cause performance prob- 
lems. 

An actionjiandling value of XTestPACKED ACTIONS causes the server to pack 
as many user input actions as possible into a XTestlnputActionType event. This 
is needed if user input actions are happening rapidly (such as when the user 
moves the pointer) to keep performance at a reasonable level. 

An actionjiandling value of XTestPACKEDJAOTION causes the server to pack 
only user input actions associated with moving the pointer. This allows ti\e 
client to receive button and key motions as they happen without waiting for the 
event to fill up, while still keeping performance at a reasonable level. 

An actionjiandling value with XTestEXCLUSIVE 'ofed in causes the server to 
send user input actions only to the client. The effect on the server is as if the 
user had performed no input actions. 

An actionjiandling value without XTestEXCLUSIVE causes the server to copy 
user input actions, sending one copy to the client, and handling the other copy 
normally (as it would if this extension were not installed). 

There are four types of input actions that are passed from the server to the 
client. They are: 

key/button state change 

This type of input action contains the keycode of the key or 
button that changed state; whether the key or button is up or 
down, and the time delay between this input action and tt\e 
previous input action. 

This type of input action contains information about the 
motion of the pointer when the pointer has only moved a 
short distance. If the pointer has moved a long distance, the 
pointer jump input action is used. 

This type of input action contains information about the 
motion of the pointer when the pointer has moved a long 
distance. 

This type of input action is used when the delay between 
input actions is too large to be held in the other input 
actions. 

The XTestGetlnput function will return -1 if there is an error, and 0 otherwise. 



pointer motions 



pointer jumps 



delays 
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An error code of BadAccess means that another client has already requested that 
user input actions be sent to it. 



XTestStoplnput 

int 

XTestStoplnput {display) 
Display ^display; 

display Specifies the connection to the X server. 

The XTestStoplnput function tells the server to stop putting information about 
user input actions into events. The server will process user input actions nor- 
mally (as it would if this extension were not in the server). 

The XTestStoplnput function will return -1 if there is an error, and 0 otherwise. 

An error code of BadAccess means that a request was made to stop input when 
input has never been started. 



XTestFakelnput 



int 

XTestFakelr^ut (display, actionjistjiddr, actionJist_size, 
ack Jiag) 
Display ^display; 

char *actionJistjiddr; 
int actionJist_size; 
int ackjlag; 



display 

actionjistjiddr 
action_list_size 
ack Jlag 



Specifies the connection to the X server. 

Specifies the address of an list of input actions to be sent to the 
server. 

Specifies the size (in bytes) of the list of input actions. It may 
be no larger than XTestMAXjiCTIONJJSTJSIZE bytes. 

Specifies whether the server needs to send an event to indicate 
that its input action buffer is empty (one of 
XTestFAKEJiCKNOTmEDED or 
XTestFAKEJiCK REQUEST). 
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The XTestFakelnput function tells the server to take the specified user input 
actions and process them as if the user had physically performed them. 

The server can only accept a limited ntunber of input actions at one time. This 
limit can be determined by the XTestQuerylnputSize function in this extension. 

The client should set ackjlag to XTesiFAKEJiCKJiOTJIEEDED on calls to 
XTestFakelnput that do not reach this limit. 

The client should set ackjag to XTestFAKEj^CKJiEQUEST on the call to XTest" 
Fakdnput that reaches this limit. 

When the server sees an ackjlag value of XFestFAKE^ACKJREQUEST it finishes 
processing its input action buffer, then sends an event with type XTestFakeAck- 
Type to the client. When the dient reads this event, it knows that it is safe to 
resume sending input actions to the server. 

Since the actual value of the event type may vary depending on how many 
extensions are included with an XI 1 implementation, XTestFakeAckType is a vari- 
able that is contained in the Xlib part of this extension. It may be referenced as 
follows: 

extern int XTestFakeAckType; 

There are four types of input actions that are passed from the client to the 
server. They are: 

key /button state change 

This type of input action contains the keycode of the key or 
button that is to change state; whether the key or button is to 
be up or down, and the time to delay before changing the 
state of the key or button. 

This type of input action contains information about the 
motion of the pointer when the pointer is to be moved a 
short distance, and the time to delay before moving the 
pointer. If the pointer is to be moved a long distance, the 
pointer jump input action must be used. 

This type of input action contains information about the 
motion of the pointer when the pointer is to be moved a long 
distance, and ti\e time to delay before moving the pointer. 



pointer motions 



pointer jumps 
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delays This type of input action is used when the delay between 

input actions is too large to be held in the other input 
actions. 

The XTestFakelnput function will return -1 if there is an error, and 0 otherwise. 

An error code of BadAccess means that another client has already sent user input 
actions to the server, and the server has not finished processing the user input 
actions. 



XTestQuerylnputSize 

int 

XTestQuerylnputSize (display, sizejetum) 
Display ^display, 
unsigned long *size_return; 

display Specifies the connection to the X server. 

sizejretum Returns the number of input actions that the server's input 

action buffer can hold. 

The XTestQuerylnputSize function asks the server to return the number of input 
actions that it can hold in its input action buffer in the unsigned long pointed to 
by sizejretum. 

The XTestQuerylnputSize function will return -1 if there is an error, and 0 other- 
wise. 

XTestReset 

int 

XTestReset (display) 
Display ^display; 

display Specifies the connection to the X server. 
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The XTestReset function tells the server to set everything having to do with this 
extension back to its initial state. After this call the server will act as if this 
extension were not installed until one of the extension functions is called by a 
client. This function is not normally needed, but is included in case a client 
wishes to clean up the server state, such as after a serious error. 

The XTestReset function will return -1 if there is an error, and 0 otherwise. 
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/* 

* xtaatttsctl.h 
* 

* Xll Ii^t Synthesis Extension include file 
V 

/* 

/* 

* the typedefs for CARD8, CARD16, and CARD32 axe defined in Xknd.h 
V 

/* 

* used in the X!testPressButton and XTestPressKey functions 
*/ 

»def ine XTestPRESS 1 « 0 

idef ine XTestBELBASB 1 « 1 

#def ine XlestSTROKE 1 « 2 

/* 

* When doing a key or button stroke, the nisnber of milliseoonds 

* to delay between the press and the release of a key or button 

* in the XTestPressButton and ^O^estPressKey functions. 
*/ 

idef ine X!restSTiU»BJ)ELAYjrBe 10 
/* 

* used in the XTestGet Input function 
*/ 

Idef ine XTestBXCLOSIVB 1 « 0 

Idef ine XTestPiMSCEDJMCrriOllS 1 « 1 

tdaf ine XTestPJMSCEDJOTIQN 1 « 2 

/* 

* used in the XS^stFakelnput function 
*/ 

idef ine XTestFirajyC3CJI0TJIEEDED 0 
Idef ine XTestFiaCEJU3CJ<BQUEST 1 
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/* 

* used in the XTest extension initialization routine 
*/ 

Idefine XTestEXIENSIONJIAMB "XlestExtensionl" 
fdefine XTestEVEMTOOUNT 2 

/* 

* XTest request type values 
* 

* used in the XTest extension protocol requests 



Idefine X_TestFakeIi^t 1 

Idefine X_TestGetInput 2 

Idefine XJTestStopIr^t 3 

Idefine X_TestReset 4 

Idefine XJTestQuery Inputs ize 5 



/* 

* This defines the maximum size of a list of ir^ut actions 

* to be sent to the server. It should always be a multiple of 

* 4 so that the entire xTestFakelnputReq structure size is a 

* multiple of 4. 
*/ 

Idefine XTestMAXjy^TIONJiIST^SIZE 64 

typedef struct { 

CARD8 reqType; /* always XTestReqCode */ 

CARDS XTestRec^ype; /* always XJTestFalcelnput */ 
CARD16 length B16; /* 2 + XTestMMC_ACTION_LISTJ5IZE/4 */ 
CARD32 ack B32; 

CARD8 action_list [XTestMAX_ACTION_LIST_SIZE] ; 
} xTestFakelnputFeq; 

Idefine szjxTestFakelnputBeq (XTestMAX_ACTION_LIST_SIZE + 8) 

typedef struct { 

CARD8 reqType; /* always XTestReqCode V 

CARD8 XTestReqType; /* always X_TestGetIr^t */ 
CARD16 length B16; /* 2 */ 
CARD32 mode B32; 

} xTestGetlr^tReq; 
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#<tefine sz_xTe«tGetInputReq 8 

typedef struct { 

CARDS ceqt^Type; 

CARD8 XTestRaqtType; 

CARD16 length B32; 
} a^eBtStopInputBaq; 
#def ine sz^x^TestStopInputReq 4 



/* always XTestlteciCode */ 
/* always XJTestStopInput */ 
/* 1 */ 



typedef struct { 

CARDS reqType; /* always 3CTestRs(|Coda */ 

CARDS X!testReG[Type; /* always XJTestReset */ 
CARD16 length B16; /* 1 V 

> xTestResetReq; 

idefine sz_xTestResetReq 4 



typedef struct ( 

CARDS reqType; /* always X!restRe<|Code */ 

CARDS XlestReqType; /* always XJTestQuerylnputSize */ 
CARD16 length B16; /* 1 */ 

} ^estQuerylnputSizeReq; 

#def ine sz_xTestQueryIx^tSiz^Req 4 

/* 

* This is the definition of the reply for the xTestQuerylz^tSize 

* request. It should remain the same minimum size as other replies 

* (32 bytes) . 
*/ 

typedef struct { 

/* always XJleply */ 



CARDS 


type; /* 


CARDS 


padl; 


CARD16 


sequenceNunber B16; 


CARD32 


length B32; /* 


CARD32 


size_retum B32; 


CARD32 


pad2 B32; 


CARD32 


pad3 832; 


CARD32 


pad4 B32; 


CARD32 


pads B32; 


CARD32 


pad6 B32; 



} xTestQuerylz^tSizeReply; 
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/* 

* This is the definition for the ix^t action wire event structure. 

* This event is sent to the client nhen the server has one or 

* more user irqput actions to repoz± to the client. It nist 

* remain the same size as all other wire events (32 bytes) . 
*/ 

fdef ine XTestACTIONSJSIZE 28 

typedef struct { 

CARDS type; /* always XTestli^tActionType */ 

CARD8 padOO; 

CABD16 sequenoeNunber B16; 

CARD8 actions [XTestiy:TIOKS_SIZE] ; 
} xTestlixputActionBvent; 

/* 

* This is the definition for the ^^stFalceAck wire event structure. 

* This event is sent to the client when the server has conpletely 

* processed its input action buffer, and is ready for more. 

* It must remain the same size as all other wire events (32 bytes) . 
*/ 

typedef struct { 

CARD8 type; /* always XTestFakeAdcType V 

CARD8 padOO; 

CARD16 sequenceNunber B16; 

CARD32 pad02 B32; 

CARD32 pad03 B32; 

CaRD32 pad04 B32; 

CABD32 pad05 B32; 

CARD32 pad06 B32; 

CARD32 pad07 B32; 

CARD32 pad08 B32; 
} sAestFakeAckEvent; 

/* 

* The server side of this extension does not (and should not) have 

* definitions for Display and Window. The ifndef allows the server 

* side of the extension to ignore the following typedef s. 
*/ 

tifndef XTestSERVER SIDE 
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/* 

* This is the dafinition for the input ac±ion host format event structure. 

* This is the form that a client using this extension will see idMn 

* it receives an ii^nit action event. 
*/ 

typedef struct { 

int type; /* always XTest Input Act ionType */ 

Display Misplay; 
Window window; 

CARDS actions [XTestACTIONS_SIZE] ; 
} XTest InputActionEvent; 

/* 

* This is the definition for the adTestFakeAck host format event structure. 

* This is the form that a client using this extension will see when 

* it receives an XTestFakeAck event. 
*/ 

typedef struct { 

int type; /* always XTestFakeAclcType */ 

Display ^display; 

Window window; 
} XTestFakeAckEvent; 
fendif 

/* 

* This is the definition for the format of the header byte 

* in the input action structures. 
*/ 

0x03 /* bits 0 and 1 */ 

0x04 /* bit 2 (Icey action) */ 

0x04 /* bit 2 (motion action) */ 

0x08 /* bit 3 (motion action) */ 

OxfO /* bits 4 throu* 7 */ 

OxOf 

(((x) & XTestMMCJ)EVICE_ID) « 4) 
(((X) € XTestDEVICE_ID_MASK) » 4) 



#def ine XTestACTICNJTYPEJMASK 
#def ine XTestKEYJ5TATE_MASK 
fdefine XTestXJSIGN_BITJfASK 
idefine XTestYJ5IGN_BITJMASK 
Idef ine XTestDEVICE_IDJASK 

#def ine XTestMAXJ)EVICE_ID 
idefine XTestPackDevicelD (x) 
idefine XTestUi^padcDevicelD (x) 



X11 Input Synthesis Extension 



E-19 



X1 1 Input Synthesis Extension Include File 



/* 

* These are the possible action types. 
*/ 

fdefine XTestDELAY^ACTIOM 0 

#def ine XlestKEYJM^TION 1 

fdefine XTestMDTIOllJCTION 2 

fdefine Xlest JlA4PjyCTI0N 3 

/* 

* These are the definitions for key/button motion input actions. 
V 

fdefine XTestKEYJOP 0x04 
fdefine XTestKEYJX)NH 0x00 

typedef struct { 

CARD8 header; /* iftiich device, key up/down */ 

CARD8 keycode; /* Whidi Icey/button to move 

CARD16 delayjtime B16; /* how long to dalay (in ns) */ 

} XTestKeylnfo; 

/* 

* This is the definition for pointer junp input actions. 
V 

typedef struct { 



CARDS 


header ; 


/* 


Whicii pointer 


*/ 


CARD8 


padl; 


/* 


unused padding byte 


V 


CARD16 


junpx B16; 


/* 


x coord to jump to 


*/ 


CARD16 


jumpy B16; 


/* 


y coord to jump to 


V 


CARD16 


delayjtime Bl€; 


/* 


how long to delay (in ms) 


*/ 



} XTestJtDopInfo; 
/* 

* These are the definitiocw for pointer relative motion input 

* actions. 
* 

* The sign bits for the x and y relative notions are contained 

* in the header byte. The x and y relative motions are packed 

* into one byte to make things fit in 32 bits. If the relative 

* motion range is larger than +/-15, use the pointer juoop action. 
V 
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idef Ine XTMtMDTIONJAX 15 

idbf iM acre«tic>iic»nMDi -15 

tdttf ins XTestXJlBGATIVB 0x04 

#daf ina XTestYJMBGATIVB 0x08 

idef ine XlestXJHDTIOIIJASK OxOf 

idef iiie XTestY MOTION MASK OxfO 



Idef ine XlestPackXMotionValue (x) ((x) fi X!testXJbX>IIOIIJASK) 

idef ine XlestPacIcYMoticMiValue (x) (((x) « 4) C XTeetYJOTIONMASK) 

ideflzie XTe8tUti|>ackXMotionValue (x) ((x) £ XTestXJOIIONJASK) 

idef ine XTeetlftipeGkYMotionValue (x) (((x) € XTestYJOTIONMASK) » 4) 

typedef struct ( 

CARD8 header; /* whidi pointer */ 

CARDS notionjdata; /* x,y relative motion */ 

CARD16 delayj:ime B16; /* how long to delay (in ms) V 

} XTestMotionlnfo; 



/* 

* These are the definitions for a long delay input action. It is 

* used when more than ]CrestSIiORT_DELAY_TIMB milliseconds of delay 

* (approximately one minute) is needed . 
* 

* The device ID for a delay is always set to XTestDEIAYJ)EVICE_ID . 

* This guarantees that a header byte with a value of 0 is not 

* a valid header, so it can be used as a flag to indicate that 

* there are no more input actions in an XlestlnputAction event. 
*/ 

idef ine XTestSHC^J»LAY_TIMB Oxf f ff 
idef ine XTestDELAYJSVICE_ID OxOf 



typedef struct { 

CARDS beader; 

CARD8 padl; 

CARD16 pad2 B16; 

CARD32 delayjtlme B32; 
> XTestDelaylnfo; 



/* always XTestDEIAYJDEVICE^ID */ 
/* unused padding byte */ 
/* unused padding word */ 
/* how long to delay (in ms) */ 
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X maintains a list of hosts from which client pro- 
grams can be run. By default only programs on the 
local host and hosts specified in an initial list read by 
the server can use the display. This access control 
list can be changed by clients on the local host. Some 
server implementations can also implement other 
authorization mechanisms in addition to or in place 
of this mechanism. The action of this mechanism can 
be conditional based on the authorization protocol 
name and data received by the server at connection 
setup. 

A grab is active when the pointer or keyboard is 
actually owned by the single grabbing client. 

If W is an inferior of A, then A is an ancestor of W. 

An atom is a unique ID corresponding to a string 
name. Atoms are used to identify properties, types, 
and selections. 

An InputOutput window can have a background, 
which is defined as a pixmap. When regions of the 
window have their contents lost or invalidated, the 
server automatically tiles those regions with the 
background. 

When a server maintains the contents of a window, 
the pixels saved off-screen are known as a backing 
store. 

When a window is resized, the contents of the win- 
dow are not necessarily discarded. It is possible to 
request that the server relocate the previous contents 
to some region of the window (though no guarantees 
are made). This attraction of window contents for 
some location of a window is known as bit gravity. 

When a pixmap or window is thought of as a stack 
of bitmaps, each bitmap is called a bit plane or plane. 
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Button grabbing 



Byte order 



Children 
Class 

Client 



Clipping region 



A bitmap is a pixmap of depth one. 

An ir^utOutput window can have a border of equal 
thickness on all four sides of the window. The con- 
tents of the border are defined by a pixmap, and the 
server autoniatically maintains the contents of the 
border. Exposure events are never generated for 
border regions. 

Buttons on the pointer can be passively grabbed by a 
client. When the button is pressed, the pointer is 
then actively grabbed by the client 

For image (pixmap /bitmap) data, the server defines 
the byte order, and clients with different native byte 
ordering must swap bytes as necessary. For all other 
parts of the protocol, the client defines the byte 
order, and the server swaps bytes as necessary. 

The children of a window are its first-level subwin- 
dows. 

Windows can be of different classes or types. See the 
entries for inputOnly and inputOutput windows 
for further infonnation about valid window types. 

An application program connects to the window sys- 
tem server by some interprocess communication 
(IPC) path, such as a TCT connection or a shared 
memory buffer. This program is referred to as a 
client of the window system server. More precisely, 
the client is the IPC path itself. A program with mul- 
tiple paths open to the server is viewed as multiple 
clients by the protocol. Resource lifetimes are con- 
trolled by connection lifetimes, not by program life- 
times. 

In a graphics context, a bitmap or hst of rectangles 
can be specified to restrict output to a particular 
region of the window. The in\age defined by the bit- 
map or rectangles is called a clipping region. 
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Colormap A colormap consists of a set of entries defining color 

values. The colormap associated with a window is 
used to display the contents of the window; each 
pixel value indexes the colormap to produce RGB 
values that drive the guns of a nwnitor. Depending 
on hardware limitations, one or more colonnaps can 
be installed at one time so that windows associated 
with those maps display with true colors. 

Connection The IPC path between the server and client program 

is known as a connection. A client program typically 
(but not necessarily) has one connection to the server 
over which requests and events are sent. 

Containment A window contains the pointer if the window is 

viewable and the hotspot of the cursor is within a 
visible region of the window or a visible region of 
one of its inferiors. The border of the window is 
included as part of the window for containment. The 
pointer is in a window if the window contains the 
pointer but no inferior contains the pointer. 

Coordinate system The coordinate system has X horizontal and Y verti- 
cal, with the origin [0, 0] at the upper left. Coordi- 
nates are discrete and are in terms of pixels. Each 
window and pixmap has its own coordinate system. 
For a window, the origin is inside the border at the 
inside upper-left comer. 

A cursor is the visible shape of the pointer on a 
screen. It consists of a hotspot, a source bitmap, a 
shape bitmap, and a pair of colors. The cursor 
defined for a window controls the visible appearance 
when the pointer is in that window. 

The depth of a window or pixmap is the number of 
bits per pixel it has. The depth of a graphics context 
is the depth of the drawables it can be used in con- 
junction with graphics output 



Cursor 



Depth 
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Device 



DirectColor 



Display 



Drawable 



Event 



Keyboards, mice, tablets, track-balls, button boxes, 
and so on are all collectively known as input devices. 
Pointers can have one or more buttons (the most 
common number is three). The core protocol only 
deals with two devices: the keyboard and the 
pointer. 

DirectColor is a class of colormap in which a pixel 
value is decomposed into three separate subfields for 
indexing. The first subfield indexes an array to pro- 
duce red intensity values. The second subfield 
indexes a second array to produce blue intensity 
values. The third subfield indexes a third array to 
produce green intensity values. The RGB (red, green, 
and blue) values in the colormap entry can be 
changed d3mamically. 

A server, together with its screens and input devices, 
is called a display. The Xlib Display structure con- 
tains all information about the particular display and 
its screens as well as the state tttat Xlib needs to com- 
municate with the display over a particular connec- 
tion. 

Both windows and pixmaps can be used as sources 
and destinations in graphics operations. These win- 
dows and pixmaps are collectively known as draw- 
ables. However, an inputOnly window cannot be 
used as a source or destination in a graphics opera- 
tion. 

Clients are informed of information asynchronously 
by means of events. These events can be either asyn- 
chronously generated from devices or generated as 
side effects of client requests. Events are grouped 
into types. The server never sends an event to a 
client unless the client has specifically asked to be 
informed of that type of event. However, clients can 
force events to be sent to other clients. Events are 
typically reported relative to a window. 
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Event propagation 



Event synchronization 



Event souroe 



Exposure event 



Extension 



Font 



Frozen events 



Events are requested relative to a window. The set of 
event types a client requests relative to a window is 
described by using an event mask. 

Device-related events propagate from the source win- 
dow to ancestor windows until some client has 
expressed interest in handling that type of event or 
until the event is discarded explicitly. 

There are certain race conditions possible when 
demultiplexing device events to clients (in particular, 
deciding where pointer and keyboard events should 
be sent when in the middle of window management 
operations). The event synchronization mechanism 
allows synchronous processing of device events. 

The deepest viewable window that the pointer is in 
is called the source of a device-related event. 

Servers do not guarantee to preserve the contents of 
windows when windows are obscured or 
reconfigured. Exposure events are sent to clients to 
inform them when contents of regions of windows 
have been lost 

Named extensions to the core protocol can be 
defined to extend the system. Extensions to output 
requests, resources, and event types are all possible 
and expected. 

A font is an array of glyphs (tj^^ically characters). 
The protocol does no translation or interpretation of 
character sets. The client simply indicates values used 
to index the glyph array. A font contains additional 
metric information to determine interglyph and inter- 
line spacing. 

Clients can freeze event processing during keyboard 
and pointer grabs. 
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GC is an abbreviation for graphics context. See 
Graphics context. 

A glyph is an image in a font, typically of a charac- 
ter. 

Keyboard keys, the keyboard, pointer buttons, the 
pointer, and the server can be grabbed for exclusive 
use by a client In general, these facilities are not 
intended to be used by normal applications but are 
intended for various input and window managers to 
implement various styles of user interfaces. 

Various information for graphics output is stored in 
a graphics context (GC), such as foreground pixel, 
background pixel, line width, clipping region, and so 
on. A graphics context can only be used with draw- 
ables that have the same root and the same depth as 
the graphics context 

The contents of windows and windows themselves 
have a gravity, which determines how the contents 
move when a window is resized. See Bit gravity 
and Window gravity. 

Grayscale can be viewed as a degenerate case of 
Pseudocolor, in which the red, green, and blue 
values in any given colormap entry are equal and 
thus, produce shades of gray. The gray values can 
be changed dynamically. 

A cursor has an associated hotspot, which defines the 
point in the cursor corresponding to the coordinates 
reported for the pointer. 

An identifier is a unique value associated with a 
resource that clients use to name that resource. The 
identifier can be used over any connection to name 
the resource. 

The inferiors of a window are all of the subwindows 
nested below it: the children, the children's children, 
and so on. 
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Input nanager 



InputOnly window 



InputOutput window 



Key grabbing 



Keyboard grabbing 



Keysym 
Mapped 



The input focus Is usually a window defining the 
scope for processing of keyboard input. If a gen- 
erated keyboard event usually would be reported to 
this window or one of its inferiors, the event is 
reported as usual. Otherwise, the event is reported 
with respect to the focus window. The input focus 
also can be set such that all keyboard events are dis- 
carded and such that the focus window is dynami- 
cally taken to be the root window of whatever screen 
the pointer is on at each keyboard event 

Control over keyboard input is typically provided by 
an input manager dient, which usually is part of a 
window manager. 

An InputOnly window is a window that cannot be 
used for graphics requests. InputOnly windows are 
invisible and are used to control such things as cur- 
sors, input event generation, and grabbing. Inpu- 
tOnly windows cannot have InputOutput windows 
as inferiors. 

An InputOutput window is the normal kind of win- 
dow that is used for both input and output. Inpu- 
tOutput windows can have both InputOutput and 
InputOnly windows as inferiors. 

Keys on the keyboard can be passively grabbed by a 
client. When the key is pressed, the keyboard is then 
actively grabbed by the client. 

A client can actively grab control of the keyboard, 
and key events will be sent to that client rather than 
the dient to which the events would normally have 
been sent 

An encoding of a symbol on a keycap on a keyboard. 

A window is said to be mapped if a map call has 
been performed on it Unmapped windows and 
their inferiors are never viewable or visible. 
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Shift, Control, Meta, Super, Hyper, Alt, Compose, 
Apple, CapsLock, ShiftLock, and sinular keys are 
csdled modifier keys. 

Monochrome is a special case of StaticGray in 
which there are only two colormap entries. 

Window A obscures window B if both are mapped, if 
A is higher in the global stacking order, and if the 
rectangle defined by the outside edges of A intersects 
the rectangle defined by the outside edges of 6. 
Note that InputOnly windows cannot obscure other 
windows. 

Window A occludes window B if A is higher in the 
global stacking order, and if the rectangle defined by 
the outside edges of A intersects the rectangle 
defined by the outside edges of B. The (fine) distinc- 
tion between the terms obscures and occludes is that 
for obscures, the windows have to be mapped, while 
for occludes they don't. Also note that window bord- 
ers are included in the calculation. Note that Inpu- 
tOnly windows never obscure other windows but 
can occlude other windows. 

Some padding bytes are inserted in the data stream 
to maintain alignment of the protocol requests on 
natural boundaries. This increases ease of portability 
to some machine architectures. 

If C is a child of P, then P is the parent of C. 

Grabbing a key or button is a passive grab. The grab 
activates when the key or button is actually pressed. 

A pixel is an N-bit value, where N is the number of 
bit planes used in a particular window or pixmap 
(that is, is the depth of the window or pixmap). A 
pixel in a window indexes a colormap to derive an 
actual color to be displayed. 
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A pixmap is a three-dimensional array of bits. A pix- 
map is normally thought of as a two-dimensional 
array of pixels, where each pixel can be a value from 
0 to 2^-1, and where N is the depth (z axis) of the 
pixmap. A pixmap can also be thought of as a stack 
of N bitmaps. A pixmap can only be used on the 
screen that it was created in. 

When a pixmap or window is thought of as a stack 
of bitmaps, each bitmap is called a plane or bit plane. 

Graphics operations can be restricted to only affect a 
subset of bit planes of a destination. A plane mask is 
a bit mask describing which planes are to be 
modified. The plane mask is stored in a graphics 
context. 

The pointer is the pointing device currently attached 
to the cursor and tracked on the screens. 

A client can actively grab control of the pointer. Then 
button and motion events will be sent to that client 
rather than the client the events would nomnally 
have been sent to. 

A pointing device is typically a mouse, tablet, or 
some other device with effective dimensional motion. 
The core protocol defines only one visible cursor, 
which tracks whatever pointing device is attached as 
the pointer. 

Windows can have associated properties that consist 
of a name, a type, a data format, and some data. The 
protocol places no interpretation on properties. They 
are intended as a general-purpose naming mechan- 
ism for clients. For example, clients might use pro- 
perties to share information such as resize hints, pro- 
gram names, and icon formats with a window 
manager. 
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The property list of a window is the list of properties 
that have been defined for the window. 

Pseudocolor is a class of colormap in which a pixel 
value indexes the colormap entry to produce 
independent RGB values; that is, the colormap is 
viewed as an array of triples (RGB values). The RGB 
values can be changed dynamically. 

A rectangle specified by [x,y,w,h] has an infinitely 
thin outline path with comers at [x,y], [x+w,y], 
[x+w,y+h], and [x, y+h]. When a rectangle is filled, 
the lower-right edges are not drawn. For example, if 
w=h=0, nothing would be drawn. For w=h=l, a sin- 
gle pixel would be drawn. 

Window managers (or client programs) may enforce 
window layout policy in various ways. When a client 
attempts to change the size or position of a window, 
the operation may be redirected to a specified client 
rather than the operation actually being performed. 

Information requested by a client program using the 
X protocol is sent back to the client with a reply. 
Both events and replies are multiplexed on the same 
connection. Most requests do not generate replies, 
but some requests generate multiple replies. 

A command to the server is called a request. It is a 
single block of data sent over a connection. 

Windows, pixmaps, cursors, fonts, graphics contexts, 
and colormaps are known as resources. They all have 
unique identifiers associated with them for naming 
purposes. The lifetime of a resource usually is 
bounded by the lifetime of the connection over which 
the resource was created. 

RGB values are the red, green, and blue intensity 
values that are used to define a color. These values 
are always represented as 16-bit, unsigned numbers, 
with 0 the minimum intensity and 65535 the 
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Root window 



Save set 



Scanline 



Scanline order 



Screen 



Selection 



maximum intensity. The XWIN server scales these 
values to match the display hardware. 

The root of a pixmap or graphics context is the same 
as the root of whatever drawable was used when the 
pixmap or GC was created. The root of a window is 
the root window under which the window was 
created. 

Each screen has a root window covering it. The root 
window cannot be reconfigured or unmapped, but 
otherwise it acts as a full-fledged window. A root 
window has no parent. 

The save set of a client is a list of other clients' win- 
dows that, if they are inferiors of one of the client's 
windows at connection close, should not be des- 
troyed and that should be remapped if currently 
unmapped. Save sets are typically used by window 
n\anagers to avoid lost windows if the manager 
should terminate abnormally. 

A scanline is a list of pixel or bit values viewed as a 
horizontal row (all values having the same y coordi- 
nate) of an image, with the values ordered by 
increasing the x coordinate. 

An image represented in scanline order contains 
scanlines ordered by increasing the y coordinate. 

A server can provide several independent screens, 
which typically have physically independent moni- 
tors. This would be the expected configuration when 
there is only a single keyboard and pointer shared 
among the screens. A Screen structure contains the 
information about that screen and is linked to the 
Display structure. 

A selection can be thought of as an indirect property 
with dynamic type. That is, rather than having the 
property stored in the XwiN server, it is maintained 
by some client (the owner). A selection is global and 
is thought of as belonging to the user and being 
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maintained by clients, rather than being private to a 
particular window subhierarchy or a particular set of 
clients. When a client asks for the contents of a 
selection, it specifies a selection target type, which 
can be used to control the transmitted representation 
of the contents. For example, if the selection is "the 
last thing the user clicked on," and that is currently 
an image, then the target type might specify whether 
the contents of the image should be sent in XY for- 
mat or Z format. The target type can also be used to 
control the class of contents transmitted; for example, 
asking for the "looks" (fonts, line spacing, indenta- 
tion, and so forth) of a paragraph selection, rather 
than the text of the paragraph. The target type can 
also be used for other purposes. The protocol does 
not constrain the semantics. 

Server The server, which is also referred to as the XWIN 

server, provides the basic windowing mechanism. It 
handles IPC connections from clients, demultiplexes 
graphics requests onto the screens, and multiplexes 
input back to the appropriate clients. 

Server grabbing The server can be grabbed by a single client for 

exclusive use. This prevents processing of any 
requests from other client connections until the grab 
is completed. This is typically only a transient state 
for such things as rubber-banding, pop-up menus, or 
executing requests indivisibly. / 

Sibling Children of the same parent window are known as 

sibling windows. 

Stacking order Sibling windows, similar to sheets of paper on a 

desk, can stack on top of each other. Windows above 
both obscure and occlude lower windows. The rela- 
tionship between sibling windows is known as the 
stacking order. 
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TrueColor 



StaticColor can be viewed as a degenerate case of 
Pseudocolor in which the RGB values are 
predefined and read-only. 

StaticGray can be viewed as a degenerate case of 
Grayscale in which the gray values are predefined 
and read-only. The values are typically linear or 
near-linear increasing ramps. 

Many Xlib functions return a success status. If the 
function does not succeed, however, its arguments 
are not disturbed. 

A stipple pattern is a bitmap that is used to tile a 
region to serve as an additional clip mask for a fill 
operation with the foreground color. 

A pixmap can be replicated in two dimensions to tile 
a region. The pixmap itself is also known as a tile. 

A timestamp is a time value expressed in mil- 
liseconds. It is typically the time since the last server 
reset. Timestamp values wrap around (after about 
49.7 days). The server, given its current time is 
represented by timestamp T, always interprets times- 
tamps from clients by treating half of the timestamp 
space as being earlier in time than T and half of the 
timestamp space as being later in time than T. One 
timestamp value, represented by the constant 
CurrentTiine, is never generated by the server. This 
value is reserved for use in requests to represent the 
current server time. 

TrueColor can be viewed as a degenerate case of 
DirectColor in which the subfields in the pixel 
value directly encode the corresponding RGB values. 
That is, the colormap has predefined read-only RGB 
values. The values are typically linear or near-linear 
increasing ramps. 
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A type is an arbitrary atom used to identify the 
interpretation of property data. Types are completely 
uninterpreted by the server. They are solely for the 
benefit of clients. X predefines type atoms for many 
frequently used types, and clients also can define 
new types. 

A window is viewable if it and all of its ancestors are 
mapped. This does not imply that any portion of the 
window is actually visible. Graphics requests can be 
p>erformed on a window when it is not viewable, but 
output will not be retained unless the server is main- 
taining backing store. 

A region of a window is visible if someone looking 
at the screen can actually see it; that is, the window 
is viewable and the region is not occluded by any 
other window. 

When windows are resized, subwindows may be 
repositioned automatically relative to some position 
in the window. This attraction of a subwindow to 
some part of its parent is known as window gravity. 

Manipulation of windows on the screen and much of 
the user interface (policy) is typically provided by a 
window manager client. 

The data for a pixmap is said to be in XY format if it 
is organized as a set of bitmaps representing indivi- 
dual bit planes with the planes appearing from 
most-significant to least-significant bit order. 

The data for a pixmap is said to be in Z format if it is 
organized as a set of pixel values in scanline order. 
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UnmapNotify Event 3: 24 

V 

VendorRelease 2: 9 
Vertex D: 2 
VertexCurved D: 2 
VertexDontDraw D: 2 
VertexEndOosed D: 2 
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XDefaultGCOfScreen 2: 13 
XDefaultRcx)tWindow 2: 6 
XDefaultScreen 2: 7 
XDefaultScreenOfDisplay 2: 6 
XDefaultVisual 2: 7 
XDefaultVisualOfScreen 2: 13 
XDefineCursor 3: 17, 6: 59 
XDeleteAssoc D: 5 
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XDeleteModifiermapEntry 7: 42 
XDeleteProperty 4: 17 
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XDestroylmage 10: 28 
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XDestroyWindowEvent 8: 37 
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XDisplayKeycodes 7: 39 
XDisplayMotionBufferSize 8: 67 
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XDisplayWidthMM 2:11 
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XDrawFilled D: 3 
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XEqualRegion 10: 17 
XErrorEvent 8: 70 
XESetQoseDisplay C: 5 
XESetCopyGC C: 5 
XESetCreateFont C: 6 
XESetCreateGC C: 5 
XESetError C: 9 
XESetErrorString C: 9 
XESetEventToWire C: 8 
XESetHushGC C: 10 
XESetPreePont C: 7 
XESetPreeGC C:6 
XESetWireToEvent C: 7 
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XFlush 8: 55 
XFlushGCCache C: 13 
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XFocusOutEvent 8: 22 
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XForceScreenSaver 7: 46 
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XFreeFont 6: 29 
XFreeFontlnfo 6: 32 
XFreeFontNames 6: 31 
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XFreeGC 5: 29 
XFreeModifiermap 7: 43 
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XGContextFromGC 5: 29 
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XGetAtomName 4: 11 
XGetClassHint 9:19 
XGetDefault 10: 7 
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XGetErrorText 8: 74 
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XGetKeyboardControl 7: 32 
XGetKeyboardMapping 7: 39 
XGetModifierMapping 7: 44 
XGetMotionE vents 8: 67 
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XGetPixel 10: 27 
XGetPointerControl 7: 36 
XGetPointerMapping 7: 35 
XGetScreenSaver 7: 47 
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XGetSizeHints 9: 16 
XGetStandardColormap 9: 26 
XGetSublmage 6: 51 
XGetTransientForHint 9: 20 
XGetVisuallnfo 10: 23 
XGetWindow Attributes 4: 2 
XGetWindowProperty 4: 12 
XGetWMHints 9:11 
XGetZoomHints 9: 15 
XGrabButton 7: 13 
XGrabKey 7:18 
XGrabKeyboard 7: 16 
XGrabPointer 7: 9 
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XGraphicsExposeEvent 8: 31 
XGravityEvent 8: 38 
XHeightMMOfScreen 2: 14 
XHeightOfScreen 2: 14 
XHostAddress 7: 49 
XlconSize 9: 17 
Xlffivent 8: 58 
Xlmage 6: 47 
XlmageByteOrder 2: 10 
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XlnsertModifiermapEntry 7: 42 
XInstallColormap 7: 6 
XIntemAtom 4: 10 
XlntersectRegion 10: 15 
XKeyboardControl 7: 30 
XKeyboardState 7: 32 
XKeycodeToKeysym 10: 5 
XKeyEvent 8: 14 
XKeymapEvent 8: 29 
XKeyPressedEvent 8: 14 
XKeyReleasedEvent 8: 14 
XKeysymToKeycode 10: 6 
XKeysymToString 1 0: 5 
XKillQient 7: 28 

XLastKnownRequestProcessed 2: 8 
XLeaveWindowEvent 8: 17 
XListExtensions C: 2 
XListFonts 6: 31 
XListFontsWithlnfo 6: 32 
XListHosts 7: 50 
XListlnstalledColormaps 7: 7 
XListProperties 4: 14 
XLoadFont 6: 28 
XLoadQueryFont 6: 29 
XLookUpAssoc D: 5 
XLookupColor 5: 7 
XLookupKeysym 10: 2 
XLookupString 7:38, 10:3 
XLowerWindow 3: 32 
XMakeAssoc D: 5 
XMapEvent 8: 38 
XMappingEvent 8: 39 
XMapRaised 3: 22 
XMapRequestEvent 8: 46 
XMapSubwindows 3: 23 
XMapWindow 3: 5, 21-22 
XMaskEvent 8: 61 
XMatchVisuallnfo 10: 23 



XMaxCmapsOfScreen 2: 14 
XMaxRequestSize C: 18 
XMinCmapsQfScreen 2: 15 
XModifierKeymap 7: 42 
XMotionEvent 8: 15 
XMoveResizeWindow 3: 30 
XMoveWindow 3: 28 
XNewModifiermap 7: 42 
XNextEvent 8: 55, 57 
XNextRequest 2: 8 
XNoExposeEvent 8: 31 
XNoOp 2: 16 
XOffsetRegion 10: 15 
XOpenDisplay 2: 2, 8: 1 
XParseColor 10: 12 
XParseGeometry 10: 9 
XPeekEvent 8: 57 
XPeeklfEvent 8: 59 
XPending 8: 55-56 
Xpermalloc 10: 38 
XPlanesOfScreen 2: 15 
XPoint 6: 7 

XPointerMovedEvent 8: 15 
XPointlnRegion 10: 18 
XPolygonRegion 10: 13 
XPropertyEvent 8: 50 
XProtocolRevision 2: 8 
XProtocolVersion 2: 8 
XPutBackEvent 8: 64 
XPutlmage 6: 48 
XPutPixel 10: 27 
XQLength 2: 9 
XQueryBestCursor 6: 54, 58 
XQueryBestSize 5: 35 
XQueryBestStipple 5: 36 
XQueryBestTile 5: 36 
XQueryColor 5: 14 
XQueiyColors 5: 14 
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XQueryExtension C: 2 
XQueryFont 6: 29 
XQueryKeymap 7: 34 
XQueryPointer 4: 6 
XQueryTextExtents 6: 37 
XQueryTextExtentsl6 6: 38 
XQueryTree 4: 2 
XRaiseWindow 3: 32 
XReadBitmapFile 10: 30 
XRebindKeysym 10: 4 
XRecolorCursor 6: 57 
XRectangle 6: 7 
XRectlnRegion 10: 18 
XRefreshKeyboardMapping 10: 3 
XRemoveFromSaveSet 7: 6 
XRemoveHost 7: 50 
XRemoveHosts 7: 51 
XReparentEvent 8: 40 
XReparentWindow 7: 2 
XReply C: 26 
XResetScreenSaver 7: 46 
XResizeRequestEvent 8: 47 
XResizeWindow 3: 29 
XResourceManagerString 10: 7 
xResourceReq C: 19 
XRestackWindows 3: 34 
XrmGetFileDatabase 1 0: 47 
XrmGetResource 10: 44 
XrmGetStringDatabase 10: 48 
Xrmlnitialize 10: 38 
XrmMergeDatabases 10: 47 
XrmOptionDescRec 10: 49 
XrmC^tionKind 10: 49 
XimParseCommand 10: 49 
XrmPutFileDatabase 10: 48 
XrmPutLineResource 10: 43 
XrmPutResource 10: 41 
XrmPutStringResource 10: 42 
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XrmQGetSearchList 1 0: 45 
XrmQGetSearchResource 10: 46 
XrmQPutResource 10: 41 
XrmQPutStringResource 10: 43 
XrmQuarkToString 1 0: 39 
XrmStringToBindingQuarkList 10: 40 
XrmStringToQuark 1 0: 39 
XrmStringToQuarkList 10: 39 
XrmUniqueQuark 10: 38 
XrmValue 10: 37 
XRootWindow 2: 9 
XRootWindowOfScreen 2: 15 
XRotateBuffers 10: 21 
XRotateWindowProperties 4: 16 
XSaveContext 10: 52 
XScreenCount 2: 9 
XScreenOfDisplay 2: 7 
XSegment 6: 7 
XSelectlnput 8: 54 
XSelectionClearEvent 8: 51 
XSelectionEvent 8: 53 
XSelectionRequestEvent 8: 51 
XSendEvent 8: 65 
XServerVendor 2: 9 
XSetAccessControl 7: 51 
XSetAfterFuiiction 8: 69 
XSetArcMode 5: 41 
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XSetClassHint 9:19 
XSetClipMask 5: 40 
XSetClipOrigin 5: 39 
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XSetCloseDownMode 7: 28 
XSetCommand 9: 8 
XSetDashes 5: 33 
XSetErrorHandler 8: 70 
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XSetFillStyle 5: 34 
XSetFont 5: 39 
XSetFontPath 6: 33 
XSetForeground 5: 31 
XSetFunction 5: 31 
XSetGraphicsExposures 5: 42 
XSetlconName 9: 7 
XSetlconSizes 9: 17 
XSetlnputFocus 7: 26 
XSetlOErrorHandler 8: 76 
XSetLineAttributes 5: 32 
XSetModifierMapping 7: 43 
XSetNormalHints 9: 13 
XSetPlaneMask 5: 32 
XSetPointerMapping 7: 34 
XSetRegion 10: 14 
XSetScreenSaver 7: 45 
XSetSelectionOwner 4: is 
XSetSizeHints 9: 15 
XSetStandardColormap 9: 27 
XSetStandardProperties 9: 4 
XSetState 5: 30 
XSetStipple 5: 37 
XSetSubwindowMode 5: 42 
XSetTile 5:37 
XSetTransientForHint 9: 20 
XSetTSOrigin 5: 38 
XSetWindowAttributes 3: 6 
XSetWindowBackground 3: 37 
XSetWindowBackgroundPixmap 
3: 37 

XSetWindowBorder 3: 38 
XSetWindowBorderPixmap 3: 39 
XSetWindowBorderWidth 3: 30 
XSetWindowColonnap 5: 5 
XSetWMHints 9:10 
XSetZoomHints 9: 14 
XShrinkRegion 10: 15 



XSizeHints 9: 12 
XStandardCoIormap 9: 23 
XStoreBuffer 10: 19 
XStoreBytes 10: 19 
XStoreColor 5:11 
XStoreColors 5: 11 
XStoreName 9: 6 
XStoreNamedColor 5: 12 
XStringToKeysym 1 0: 5 
XSublmage 10: 27 
XSubtractRegion 10: 16 
XSync 1:3, 8:55 
XSynchronize 8: 69 
XTextExtents 6: 35 
XTextExtentsl6 6: 36 
XTextltem 6: 40 
XTextIteml6 6: 40 
XTextWidth 6: 34 
XTextWidthl6 6:34-35 
XTimeCoord 8: 68 
XTranslateCoordinates 3: 40 
XUndefineCursor 6: 59 
XUngrabButton 7: 15 
XUngrabKey 7: 19 
XUngrabKeyboard 7: 17 
XUngrabPointer 7: 12 
XUngrabServer 7: 24 
XUninstallColormap 7: 6 
XUnionRectWithRegion 10: 16 
XUnionRegion 10: 16 
XUniqueContext 10: 53 
XUnloadFont 6: 30 
XUnmapEvent 8: 41 
XUnmapSubwindows 3: 24 
XUnmapWindow 3: 24 
XVendorRelease 2: 9 
XVisibilityEvent 8:43 
XVisuallDFromVisual 3: 3 
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XVisuallnfo 10: 22 
XWarpPointer 7: 25 
XWhitePixel 2: 5 
XWhitePixelOf Screen 2: 12 
XWidthMMOfScreen 2: 14 
XWidthOfScreen 2: 14 
XWindow Attributes 4: 3 
XWindowChanges 3: 25 
XWindowEvent 8: 55, 60 
XWMHints 9:9 
XWriteBitmapFile 10: 31 , 33 
XXorRegion 10: 17 
XY format G: 14 
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NAME 

AUPlanes, BlackPixel, WhitePixel, ConnectionNumber, DefaultColormap, 
DefaultDepth, DefaultGQ DefaultRootWindow, DefaultScreenOfDisplay, 
DefaultScreen, DefaultVisual, DisplayCells, DisplayPlanes, DisplayString, 
LastKnownRequestProcessed, NextRequest^ ProtocolVersion, ProtocolRevision, 
QLength, RootWindow, ScreenCoimt, ScreenOfDisplay, ServerVendor, Ven- 
dorRelease - Display macros 

SYNTAX 

AUPlanesO 

BlackPixel (iispky, screenjiumher) 
WhitePixel((^zsp^y, screen jiumber) 
ConnectionNumber {display) 
DefaultColormap (ii^/«y, screenjiumber) 
DeiauliDepih(displajf, screenjiumber) 
Defa\i\tGC(display, screenjiumber) 
DefaultRoot Window (display ) 
DefaultScreenOfDisplay ( i^ispky ) 
DefaultScreen (display) 
DefaultVisual (i^ispky, screenjiumber) 
DisplayCe\\s(display , screenjiumber) 
DisplayPlanes (izsplfly, screenjiumber) 
DisplayStnng(display) 
LastKnownRequestProcessed (display) 
NextRequest (display) 
ProtocolVersion (display) 
ProtocolRevision (display) 
QLength (display) 

RooiWindow (display, screenjiumber) 
ScreenCount(display) 
ScreenOfDisplay (iispky, screenjiumber) 
ServerVendoHdisplay) 
VendorRelease(display) 
ARGUMENTS 

display Specifies the connection to the XwiN server. 

screenjiumber Specifies the appropriate screen number on the host server. 
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DESCRIPTION 

The AllPlanes macro returns a value with all bits set to 1 suitable for use in a 
plane argument to a procedure. 

The BlackPixel macro returns the black pixel value for the specified screen. 

The WhitePixel macro returns the white pixel value for the specified screen. 

The ConnectionNumber macro returns a connection number for the specified 
display. 

The DefaultColomiap macro returns the defoult colormap ID for allocation on 
the specified screen. 

The DefauItDepth macro returns the depth (number of planes) of the default 
root window for the specified screen. 

The DefaultGC macro returns the default GC for the root window of the 
specified screen. 

The DefaultRootWindow macro returns the root window for the default screen. 

The DefaultScreenOfDisplay macro returns the default screen of the specified 
display. 

The DefaultScreen macro returns the default screen number referenced in the 
XOpenDisplay routine. 

The DefaultVisual macro returns the default visual type for the specified screen. 

The DisplayCells macro returns the number of entries in the default colormap. 

The DisplayPlanes macro returns the depth of the root window of the specified 
screen. 

The DisplayString macro returns the string that was passed to XOpenDisplay 
when the current display was opened. 

The LastKnownRequestProcessed macro extracts the full serial number of the 
last request known by Xlib to have been processed by the XwiN server. 

The NextRequest macro extracts the full serial number that is to be used for the 
next request. 

The ProtocolVersion macro returns the major version number (11) of the X pro- 
tocol associated with the connected display. 

The ProtocolRevision macro returns the minor protocol revision number of the 
XwiN server. 

The QLength macro returns the length of the event queue for the connected 
display. 

The RootWindow macro returns the root window. 

The ScreenCount macro returns the number of available screens. 

The ScreenOfDisplay macro returns a pointer to the screen of the specified 
display. 
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The ServerVendor macro returns a pointer to a null-terminated string that pro- 
vides some identification of the owner of the XwiN server implementation. 

The VendorRelease macro returns a number related to a vendor's release of the 
XwiN server. 

SEE ALSO 

BlackPixelOfScreenOXllX 

ImageByteOrder(3Xll), 

IsCursorKey(3Xll) 

Xlib - C Language X Interface 
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NAME 

BlackPixelOfScreen, WhitePixelOfScreen, CellsOfScreen, 

DefaultColormapOfScreen, DefaultDepthOfScreen, DefaultGCQfScreen, 
DefaultVisualOScreen, DoesBackingStore, DoesSaveUnders, DisplayOfScreen, 
EventMaskOfScreen, HeightOfScreen, HdghtMMOfScreen, MaxCmapsOfScreen, 
MinCmapsOfScreen, PlanesOfScreen, RootWindowQfScreen, WidthOfScreen, 
WidthMMOfScreen - screen inforniation macros 

SYNTAX 

BlackPixelOfScreen ( screen ) 

WhitePixelOfScreen ( screen ) 
CellsOfScreen ( screen ) 
DefaultColormapOf Screen ( screen ) 
DefaultDepthOf Screen ( screen ) 
Def aultGCOfScreen ( saeen ) 
DefaultVisualOfScreen (screen ) 
DoesBackingStore ( screen ) 
DoesSaveUnders(scrg«i) 
Displa)KDfScreen (scr^^n ) 
EventMaskOfScreen ( screen ) 
HeightOfScreen ( screen ) 
HeightMMOfScreen {screen ) 
MaxCmapsOf Screen ( screen ) 
MinCmapsOfScreen ( screen ) 
PlanesOfScreen ( screen ) 
RootWindowOfScreen {screen) 
WidthOfScreen(scr6gn) 
WidthMMOfScreen(scre«n) 
ARGUMENTS 

screen Specifies a pointer to the appropriate Screen structure. 

DESCRIPTION 

The BlackPixelOfScreen macro returns the black pixel value of the specified 
screen. 

The WhitePixelOfScreen macro returns the white pixel value of the specified 
screen. 

The CellsOfScreen macro returns the number of colormap cells in the default 
colormap of the specified screen. 

The DefaultColormapOfScreen macro returns the default colormap of the 
specified screen. 



10/89 



Page 1 



BlackPlxelOfScreen (3X1 1 ) 



BlackPixelOfScreen (3X1 1 ) 



The DefauUDepthOf Screen macro returns the default depth of the root window 
of the specified screen. 

The DefaultGCOfScreen macro returns the default GC of the specified screen, 
which has the same depth as the root window of the screen. 

The DefaultVisualOfScreen macro returns the default visual of the specified 
screen. 

The DoesBackingStore macro returns WhenMapped, NotUseful, or Always, 
which indicate whether the screen supports backing stores. 

The DoesSaveUnders macro returns a Boolean value indicating whether the 
screen supports save unders. 

The DisplayOf Screen macro returns the display of the specified screen. 

The EventMaskOf Screen macro returns the root event mask of the root window 
for the specified screen at connecti setup time. 

The HeightOfScreen macro returns the height of the specified screen. 

The HeightMMOfScreen macro returns the height of the specified screen in mil- 
limeters. 

The MaxCmapsOf Screen macro returns the maximum number of installed color- 
maps supported by the specified screen. 

The MinCmapsOfScreen macro returns the minimum number of installed color- 
maps supported by the specified screen. 

The PlanesOf Screen macro returns the number of planes in the root window of 
the specified screen. 

The RootWindowOfScreen macro returns the root window of the specified 
screen. 

The WidthOf Screen macro returns the width of the specified screen. 

The WidthMMOf Screen macro returns the width of the specified screen in mil- 
limeters. 

SEE ALSO 

AUPlanesOXll), 

ImageByteOrderOXl 1 ), 

IsCursorKeyOXll) 

Xlib - C Language X Interface 
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NAME 

ImageByteOrder, BitmapBitOrder, BitmapPad, BitmapUnit, DisplayHeight, 
DisplayHeightMM, DisplayWidth, DisplayWidthMM - image format macros 

SYNTAX 

ImageByteOrder(^i'sp2ay) 

BitmapBitOrder(^isp2ay) 
BitmapPad(<^isp%) 
BitmapUrdiidisplajf) 
DisplayHeight(iisp2ay, screenjiumber) 
DisplayHeightMM(i2sp%, screenjtumber) 
DisplayWidth(<^isp%, screenjtumber) 
DisplayWidthMM (display, screenjtumber) 
ARGUMENTS 

display Specifies the connection to the XwiN server. 

screenjtumber Specifies the appropriate screen number on the host server. 
DESCRIPTION 

The ImageByteOrder macro specifies the required byte order for images for each 
scanline imit in XY format (bitmap) or for each pixel value in Z format. 

The BitmapBitOrder macro returns LSBFirst or MSBFiist to indicate whether 
the leftmost bit in the bitmap as displayed on the screen is the least or most 
significant bit in the unit. 

The BitmapPad macro returns the number of bits that each scanline must be pad- 
ded. 

The BitmapUnit macro returns the size of a bitmap's scanline unit in bits. 

The DisplayHeight macro returns the height of the specified screen in pixels. 

The DisplayHeightMM macro returns the height of the specified screen in mil- 
limeters. 

The DisplayWidth macro returns the width of the screen in pixels. 

The DisplayWidthMM macro returns the width of the specified screen in millim- 
eters. 

SEE ALSO 

AUPlanesOXll), 

BlackPixelOfScreenOXll), 

IsCursorKeyOXll) 

Xlib - C Language X Interface 
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NAME 

IsCursorKey, IsFunctionKey, IsKeypadKey, IsMiscFunctionKey, IsModiferKey, 
IsPFKey - keysym classifiaction macros 

SYNTAX 

IsCursorKey ( A^sym ) 

IsFunctionKey (/Kysym) 
IsKeypadKey ( keysym ) 
IsMiscFunctionKey (/Kysym ) 
IsModifierKey ( keysym) 
IsPFKey(keysym) 
ARGUMENTS 

keysym Specifies the KeySym that is to be tested. 

DESCRIPTION 

The IsCursorKey macro returns True if the specified KeySym is a cursor key. 

The IsFunctionKey macro returns True if the KeySym is a function key. 

The IsKeypadKey macro returns True if the specified KeySym is a keypad key. 

The IsMiscFunctionKey macro returns True if the specified KeySym is a miscel- 
laneous function key. 

The IsModif erKey macro returns True if the specified KeySym is a modifier key. 
The IsPFKey macro returns True if the specified KeySym is a PF key. 

SEE ALSO 

AllPlanesOXll), 
BlackPixelOfScreenOXl 1), 
ImageByteOrder(3Xll) 
Xlib - C Language X Interface 
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NAME 

XAddHost, XAddHosts, XListHosts, XRemoveHost, XRemoveHosts, XSetAc- 
cessControl, XEnableAccessControl, XDisableAccessContro - control host access 

SYNTAX 

XAddHost(display, host) 
Display ^display; 
XHost Address *host; 

XAddHosis(display, hosts, numjiosts) 
Display * display) 
XHostAddress *hosts; 
int nurnjtosts; 

XHostAddress "^XListHosts (iisplay, nhostsjretum, state jetum) 
Display *display; 
int ^nhostsjretum; 
Bool *state_retum; 

XRemoveHost (ixspky, host) 
Display *display; 
XHostAddress *host; 

XRemoveHosts (iispifly, hosts, numjiosts) 
Display *display; 
XHostAddress *hosts; 
int nurnjtosts; 

XSetAccessControHdisplay, mode) 
Display * display; 
int mode; 

XEnableAccessControl (iisploy ) 
Display ^display; 

XDisableAccessControl (iiisplfly ) 
Display *display; 

ARGUMENTS 

display Specifies the connection to the XwiN server. 

host Specifies the host that is to be added or removed. 

hosts Specifies each host that is to be added or removed. 

mode Specifies the mode. You can pass EnableAccess or DisableAc- 

cess. 

nhostsjretum Returns the number of hosts currently in the access control list. 
numjiosts Specifies the number of hosts. 

state jetum Returns the state of the access control. 
DESCRIPTION 

The XAddHost function adds the specified host to the access control list for that 
display. The server must be on the same host as the client issuing the command, 
or a BadAccess error results. 
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XAddHost can generate BadAccess and BadValue errors. 

The XAddHosts function adds each specified host to the access control list for 
that display. The server must be on the same host as the client issuing the com> 
mand, or a BadAccess error results. 

XAddHosts can generate BadAccess and BadValue errors. 

The XListHosts function returns the current access control list as well as whether 
the use of the list at connection setup was enabled or disabled. XListHosts 
allows a program to find out what machines can make connections. It also 
returns a pointer to a list of host structures that were allocated by the function. 
When no longer needed, this memory should be freed by calling XFree. 

The XRemoveHost function removes the specified host from the access control 
list for that display. The server must be on the same host as the client process, or 
a BadAccess error results. If you remove your machine from the access list, you 
can no longer connect to that server, and this operation cannot be reversed unless 
you reset the server. 

XRemoveHost can generate BadAccess and BadValue errors. 

The XRemoveHosts function removes each specified host from the access control 
list for that display. The XwiN server must be on the same host as the client pro- 
cess, or a BadAccess error results. If you remove your machine from the access 
list, you can no longer connect to that server, and this operation cannot be 
reversed imless you reset the server. 

XRemoveHosts can generate BadAccess and BadValue errors. 

The XSetAccessControl function either enables or disables the use of the access 
control list at each connection setup. 

XSetAccessControl can generate BadAccess and BadValue errors. 

The XEnableAccessControl function enables the use of the access control list at 
each connection setup. 

XEnableAccessControl can generate a BadAccess error. 

The XDisableAccessContiol function disables the use of the access control list at 
each connection setup. 

XDisableAccessControl can generate a BadAccess error. 
DIAGNOSTICS 

BadAccess A client attempted to modify the access control list from other 
than the local (or otherwise authorized) host. 

BadValue Some numeric value falls outside the range of values accepted 
by the request. Unless a specific range is specified for an argu- 
ment, the full range defined by the argument's type is accepted. 
Any argument defined as a set of alternatives can generate this 
error. 

SEE ALSO 

Xlib - C Language X Interface 
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NAME 

XAUocColor, XAllocNamedColor, XAUocColorCells, XAUocColorBanes, 
XFreeColors - allocate and free colors 

SYNTAX 

Status XAWocColoT (displaj/, colormap, $creen_inj>ut) 
Display * display) 
Colormap colormap; 
XColor *screenjnj)ut; 

Status XAllocNamedColoT (display, colormap, color _mme, screen Jiefjretum, 
exactjiefjretum ) 
Display * display, 
Colormap colormap; 
char *colorjiame; 

XColor *screen_defjelum, *exact^defjretum; 

Status XAllocColorCells((izsplay, colormap, contig, planejnasksjetum, nplanes, 
pixels jeturn, npixels) 
Display * display; 
Colormap colormap; 
Bool contig; 

unsigned long plane _masksjeturn[\; 
unsigned int nplanes; 
unsigned long pixelsjreturnV\; 
unsigned int npixels; 

Status XAUocColorPlanes (Jtspijy, colormap, contig, pixels jeturn, ncolors, nreds, 
ngreens, nblues, rmaskjetum, gmask jeturn, bmaskjeturn) 
Display ^display; 
Colormap colormap; 
Bool contig; 

unsigned long pixels jeturnl ] ; 
int ncolors; 

int nreds, ngreens, nblues; 

unsigned long *rmask jeturn, *gmaskjeturn, *bmaskjetum; 

XFreeColors^display, colormap, pixels, npixels, planes) 
Display ^display; 
Colormap colormap; 
unsigned long pixelsl]; 
int npixels; 

unsigned long planes; 
ARGUMENTS 

color juane Specifies the color name string (for example, red) whose color 

definition structure you want returned. 

colormap Specifies the colormap. 

contig Specifies a Boolean value that indicates whether the planes must 

be contiguous. 
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display Specifies the connection to the XwiN server. 

exact ^defjretum Returns the exact RGB values. 

ncolors Specifies the number of pixel values that are to be returned in 

the pixels_return array. 

npixels Specifies the number of pixels. 

nplanes Specifies the number of plane masks that are to be returned in 

the plane masks array. 

nreds 

ngreens 

nblues 

Specify the number of red, green, and blue planes. The value 
you pass must be nonnegative. 

pixels Specifies an array of pixel values. 

pixels jetum Returns an array of pixel values. 

pUnejmskjreturn 

Returns an array of plane masks. 

planes Specifies the planes you want to free. 

mtaskjetum 
gmaskjretum 

hmaskjretum Return bit masks for the red, green, and blue planes. 
screen^efjrelum Returns the closest RGB values provided by the hardware. 
screenjnj>ut Specifies and returns the values actually used in the colormap. 
DESCRIPTION 

The XAllocColor function allocates a read-only colormap entry corresponding to 
the closest RGB values supported by the hardware. XAllocColor returns the 
pixel value of the color closest to the specified RGB elements supported by the 
hardware and returns the RGB values actually used. The corresponding color- 
map cell is read-only. In addition, XAllocColor returns nonzero if it succeeded 
or zero if it failed. Read-only colormap cells are shared among clients. When the 
last client deallocates a shared cell, it is deallocated. XAllocColor does not use or 
affect the flags in the XColor structure. 

XAllocColor can generate a BadColor error. 

The XAUocNamedColor function looks up the named color with respect to the 
screen that is associated with the specified colormap. It returns both the exact 
database definition and the closest color supported by the screen. The allocated 
color cell is read-only. You should use the ISO Latin-1 encoding; uppercase and 
lowercase do not matter. 

XAUocNamedColor can generate a BadColor error. 

The XAUocColorCells fimction allocates read/write color cells. The number of 
colors must be positive and the number of planes nonnegative, or a BadValue 
error results. If ncolors and nplanes are requested, then ncolors pixels and 
nplane plane masks are returned. No mask will have any bits set to 1 in common 
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with any other mask or with any of the pixels. By ORing together each pixel 
with zero or more masks, ncolors * 2"^^ distinct pixels can be produced. All of 
these are allocated writable by the request. For Grayscale or PseudoColor, each 
mask has exactly one bit set to 1. For DirectColor, each has exactly three bits set 
to 1. If contig is True and if all masks are ORed together, a single contiguous set 
of bits set to 1 will be formed for Grayscale or PseudoColor and three contigu- 
ous sets of bits set to 1 (one within each pixel subfield) for DirectColor. The 
RGB values of the allocated entries are undefined. XAUocColoiCells returns 
nonzero if it succeeded or zero if it failed. 

XAUocColorCells can generate BadColor and BadValue errors. 

The specified ncolors must be positive; and nreds, ngreens, and nblues must be 
nonnegative, or a BadValue error results. If ncolors colors, nreds reds, ngreens 
greens, and nblues blues are requested, ncolors pixels are returned; and the 
masks have nreds, ngreens, and nblues bits set to 1, respectively. If contig is 
True, each mask will have a contiguous set of bits set to 1. No mask will have 
any bits set to 1 in common with any other mask or with any of the pixels. For 
DirectColor, each mask will lie within the corresponding pixel subfield. By 
ORing together subsets of masks with each pixel value, ncolors * 2^***"***'*^^*^^ 
distinct pbcel values can be produced. All of these are allocated by the request. 
However, in the colormap, there are only ncolors * 2"^** independent red entries, 
ncolors * 2'**'**^ independent green entries, and ncolors * 2*^'*^ independent blue 
entries. This is true even for PseudoColor. When the colormap entry of a pixel 
value is changed (using XStoreColors, XStoreColor, or XStoreNamedColor), the 
pixel is decomposed according to the masks, and the corresponding independent 
entries are updated. XAUocColorPlanes returns nonzero if it succeeded or zero 
if it failed. 

XAUocColorPlanes can generate BadColor and BadValue errors. 

The XFreeColors function frees the cells represented by pixels whose values are 
in the pixels array. The planes argument should not have any bits set to 1 in 
common with any of the pixels. The set of all pixels is produced by ORing 
together subsets of the planes argument with the pixels. The request frees all of 
these pixels that were allocated by the client (using XAllocColor, XAlloc- 
NamedColor, XAUocColorCells, and XAUocColorPlanes). Note that freeing an 
individual pixel obtained from XAUocColorPlanes may not actually allow it to be 
reused imtil all of its related pixels are also freed. 

All specified pixels that are allocated by the client in the colormap are freed, even 
if one or more pixels produce an error. If a specified pixel is not a valid index 
into the colormap, a BadValue error results. If a specified pixel is not allocated 
by the client (that is, is unallocated or is only allocated by another client), a 
BadAccess error results. If more than one pixel is in error, the one that gets 
reported is arbitrary. 

XFreeColors can generate BadAccess, BadColor, and BadValue errors. 
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DIAGNOSTICS 

BadAccess 

BadAccess 
BadColor 

BadValue 



A client attempted to free a color map entiy that it did not 
already allocate. 

A client attempted to store into a read-only color map entiy. 

A value for a Colormap argument does not name a defined 
Colormap. 

Some numeric value falls outside the range of values accepted 
by the request. Unless a specific range is specified for an argu- 
ment, the full range defined by the argument's type is accepted. 
Any argument defined as a set of alternatives can generate this 
error. 



SEE ALSO 

XCreateColormapOXll), 

XQueryColorOXll), 

XStoreColorsOXll) 

XUb - C Language X Interface 
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NAME 

XAUowEvents - release queued events 
SYNTAX 

XAUowEventsC^ispZ^y, event jnode, time) 
Display ^display; 
int event jnode; 
Time time; 

ARGUMENTS 

display Specifies the connection to the XwiN server. 

event jnode Specifies the event mode. You can pass AsyncPointer, Sync- 
Pointer, AsyncKeyboard, SyncKeyboaid, Rq>layPointer, 
ReplayKeyboard, AsyncBodi, or SyncBoth. 

time Specifies the time. You can pass either a timestamp or Current- 

Time. 

DESCRIPTION 

The XAllowEvents function releases some queued events if the client has caused 
a device to freeze. It has no effect if the specified time is earlier than the last-grab 
time of the most recent active grab for the client or if the specified time is later 
than the current XwiN server time. 

XAllowEvents can generate a BadValue error. 

DIAGNOSTICS 

BadValue Some nimieric value falls outside the range of values accepted 

by the request. Unless a specific range is specified for an argu- 
ment, the full range defined by the argument's type is accepted. 
Any argument defined as a set of alternatives can generate this 
error. 

SEE ALSO 

Xlib - C Language X Interface 
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NAME 

XChangeKeyboardControl, XGetKeyboardG)ntrol, XAutoRepeatOn, XAu- 
toRepeatOff, XBell, XQueryKeymap - manipulate keyboard settings 

SYNTAX 

XChangeKeyboardControKiispl^, value jnask, values) 
Display ^display) 
unsigned long value jnask; 
XKeyboardControl *value$; 

XGetKeyboardControKiispky, valuesjetum) 
Display * display-, 
XKeyboardState ^valuesjetum; 

XAutoRepeatOn {display) 
Display *display; 

XAutoRepeatOff(i2^%) 
Display * display) 

XBe\\{display, percent) 
Display * display; 
int percent; 

XQvLeryKeymeip(display, keysjetum) 
Display * display; 
char keys_retum[32]; 

ARGUMENTS 

display Specifies the connection to the XwiN server. 

keysjetum Returns an array of bytes that identifies which keys are pressed 
down. Each bit represents one key of the keyboard. 

percent Specifies the volume for the bell, which can range from -100 to 

100 inclusive. 

value jnask Specifies one value for each bit set to 1 in the mask. 

values Specifies which controls to change. This mask is the bitwise 

inclusive OR of the valid control mask bits. 

valuesjetum Returns the current keyboard controls in the specified XKey- 
boardState structure. 

DESCRIPTION 

The XChangeKeyboardContiol function controls the keyboard characteristics 
defined by the XKeyboaidControl structure. The value_mask argument specifies 
which values are to be changed. 

XChangeKeyboardControl can generate BadMatch and BadValue errors. 

The XGetKeyboardContiol function returns the current control values for the 
keyboard to the XKeyboardState structure. 

The XAutoRepeatOn function turns on auto-repeat for the keyboard on the 
specified display. 
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The XAutoRepeatOff function tiirns off auto-repeat for the keyboard on the 
specified display. 

The XBell function rings the bell on the keyboard on the specified display, if pos- 
sible. The specified volume is relative to the base volume for the keyboard. If 
the value for the percent argument is not in the range -100 to 100 inclusive, a 
BadValue error results. The volume at which the bell rings when the percent 
argument is nonnegative is: 

base - [(base * percent) / 100] + percent 
The volume at which the bell rings when the percent argument is negative is: 

base + [(base * percent) / 100] 
To change the base volume of the bell, use XChangeKeyboardControl. 
XBell can generate a BadValue error. 

The XQueryKeymap function returns a bit vector for the logical state of the key- 
board, where each bit set to 1 indicates that the corresponding key is currently 
pressed down. The vector is represented as 32 bytes. Byte N (from 0) contains 
the bits for keys 8N to 8N + 7 with the least-significant Hi in the byte represent- 
ing key 8N. 

Note that the logical state of a device (as seen by dient applications) may lag the 
physical state if device event processing is frozen. 

DIAGNOSTICS 

BadMatch Some argument or pair of arguments has the correct tyipe and 
range but fails to match in some other way required by the 
request. 

BadValue Some numeric value falls outside the range of values accepted 
by the request. Unless a specific range is specified for an argu- 
ment, the full range defined by the argument's type is accepted. 
Any argument defined as a set of alternatives can generate this 
error. 

SEE ALSO 

XChangeKeyboardMapping(3Xll), 
XSetPointerMapping(3Xll) 
Xlib - C Language X Interface 
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NAME 

XChangeKeyboardMapping, XGetKeyboardMapping, XDisplayKeycodes, 
XSetModifierMapping, XGetModifierMapping, XNewModifiermap, 

XInsertModifiermapEntry, XDeleteModifiermapEntiy, XFreeModifierMap - mani- 
pulate keyboard encoding 

SYNTAX 

XChangeKeyboardMappingC ifspi«y, first _keycode, keysymsjperjxycode, keysyms, 
numj:odes) 

Display ^display; 
int first _key code; 
int keysytnsjxrjceycode; 
Ke5^ym *keysyms; 
int numj:odes; 

KeySym *XGetKeyboardMapping(iispZay, first Jceycode, keycodej:(mnt, 
keysyms jperjceycodejretum ) 
Display ^display, 
Kej?Code firstjosycode; 
int keycode^count; 
int *keysyrrisj)er_keycode_returri; 

XDisplayKeycodes (<^ispky, minjxy codes jretum, maxjxycodesjreturn) 
Display * display; 

int *minJkeycodesjelum, tnax_keycodes_retum; 

int XSetModifierMapping( display, modmap) 
Display *display; 
XModifierKeymap *inodmap; 

XModifierKeymap *XGetModifierMapping(iisp%) 
Display *display; 

XModifierKeymap *XNewModifiermap( max Joeys jperjnod) 
int maxJceysj)er_mod; 

XModifierKeymap *XInsertModifiermapEntry (moJm^^, key code _entry, modifier) 
XModifierKeymap *modmap; 
Ke)<bde keycode^entry; 
int modifier; 

XModifierKeymap *XDeleteModifiermapEntiy(m(xfm«p, keycode^entry, modifier) 
XModifierKeymap *modmap; 
KeyCode keycodejmtry; 
int modifier; 

XFreeModifiermap( modmap) 

XModifierKeymap *modmap; 

ARGUMENTS 

display Specifies the connection to the XwiN server. 
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first Jxycode Specifies the first KeyCode that is to be changed or returned. 

keycodejxnmt Specifies the number of KeyCbdes that are to be returned. 

Ixycode jniry Specifies the KeyCode. 

keysyms Specifies a pointer to an array of KeySyms. 

keysymsjperjosycode 

Specifies the number of KeySyms per KeyCode. 

Ixysymsjperjoeycodejeturn 

Returns the number of KeySyms per Ke)<^ode. 

maxjxysjterjnod 

Specifies the number of YjsyQode entries preallocated to the 
modifiers in the map. 

maxjxycodesjeium 

Returns the maximum number of KeyCbdes. 

min Jcey codes jetum 

Returns the minimum number of KeyCodes. 

modifier Specifies the modifier. 

modmap Specifies a pointer to the XModifierKeymap structure. 

num^codes Specifies the number of Ke3<!6des that are to be changed. 
DESCRIPTION 

The XChangeKeyboardMapping ftmction defines the symbols for the specified 
number of KeyCodes starting with first_keycode. The symbols for KeyCodes out- 
side this range remain unchanged. The number of elements in keysyms must be: 

num_codes * keysjans_per_keycode 

The specified first_keycode must be greater than or equal to min_keycode 
returned by XDisplayKeycodes, or a BadValue error results. In addition, the 
following expression must be less than or equal to max_keycode as returned by 
XDisplayKeycodes, or a BadValue error results: 

first_keycode + num_codes - 1 

KeySym number N, counting from zero, for KeyCode K has the following index 
in keysyms, counting from zero: 

(K - first_keycode) * keysyms_per_keycode + N 

The specified k^syms_per_keycode can be chosen arbitrarily by the client to be 
large enough to hold all desired symbols. A special KeySym value of NoSymbol 
should be used to fill in untised elements for individual KeyCodes. It is legal for 
NoSymbol to appear in nontrailing positions of the effective list for a KeyCode. 
XChangeKeyboardMapping generates a MappingNotify event. 
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There is no requirement that the XwiN server interpret this mapping. It is merely 
stored for reading and writing by clients. 

XOiangeKeyboardMapping can generate BadAlloc and BadValue errors. 

The XGetKeyboardMapping fimction returns the symbols for the specified 
number of KeyCodes starting with first_keycode. The value specified in 
first_keycode must be greater than or equal to min_keycode as returned by 
XDisplayKeycodes, or a BadValue error results. In addition, the following 
expression must be less than or equal to max_keycode as returned by 
XDisplayKeycodes : 

first keycode -i- keycode_coimt - 1 

If this is not the case, a BadValue error results. The number of elements in the 
KeySyms list is: 

keycode^count * keysyms_per_keycode_retum 

KeySym number counting from zero, for Ke5<Zode K has the following index 
in the list, counting from zero: 

(K - first_code) * keysyms_per_code_return + N 

The XwiN server arbitrarily chooses the keysyms_per_keycode_return value to be 
large enough to report all requested s3anbols. A special Ke3^ym value of NoSym> 
bol is used to fill in imused elements for individual Ke)<;odes. To free the 
storage returned by XGetKeyboardMapping, use XFree. 

XGetKeyboardMapping can generate a BadValue error. 

The XDisplayKeycodes fimction returns the min-keycodes and max-keycodes 
supported by the specified display. The minimimi ntimber of KeyCodes returned 
is never less than 8, and the maximum number of KeyCodes returned is never 
greater than 255. Not all KeyCodes in this range are required to have 
corresponding keys. 

The XSetModifierMapping function specifies the KeyCodes of the keys (if any) 
that are to be used as modifiers. If it succeeds, the XwiN server generates a Map- 
pingNotify event, and XSetModifierMapping returns MappingSuccess. X per- 
mits at most eight modifier keys. If more than eight are specified in the 
XModifierKeymap structure, a BadLength error results. 

The modifiermap member of the XModifierKeymap structure contains eight sets 
of max_keypermod Ke)<^odes, one for each modifier in the order Shift, Lock, 
Control, Modi, Mod2, Mod3, Mod4, and Mod5. Only nonzero KeyCodes have 
meaning in each set, and zero KeyCodes are ignored. In addition, all of the 
nonzero KeyCodes must be in the range specified by min_keycode and 
max_keycode in the Display structure, or a BadValue error results. No Key- 
Code may appear twice in the entire map, or a BadValue error results. 
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An XwiN server can impose restrictions on how modifiers can be changed, for 
example, if certain keys do not generate up transitions in hardware, if auto-repeat 
cannot be disabled on certain keys, or if multiple modifier keys are not sup- 
ported. If some such restriction is violated, the status reply is MappingFailed, 
and none of the modifiers are changed. If the new KeyCodes specified for a 
modifier differ from those currently defined and any (current or new) keys for 
that modifier are in the logically down state, XSetModifierMapping returns 
MappingBusy, and none of the modifiers is changed. 

XSetModifierMapping can generate BadAlIoc and BadValue errors. 

The XGetModifierMapping function returns a pointer to a newly created 
XModifierKeymap structure that contains the keys being used as modifiers. The 
structure should be freed after use by calling >CFieeModifiennap. If only zero 
values appear in the set for any modifier, that modifier is disabled. 

The XNewModifiermap function returns a pointer to XModifierKeymap struc- 
ture for later use. 

The XlnsertModifiermapEntiy fimction adds the specified KeyCode to the set 
that controls the specified modifier and returns the resulting XModifierKeymap 
structure (expanded as needed). 

The XDeleteModifiennapEntry fimction deletes the specified Ke)<!ode from the 
set that controls the specified modifier and returns a pointer to the resulting 
XModifierKeymap structure. 

The XFreeModifiermap function frees the specified XModifierKeymap structure. 
DIAGNOSTICS 

BadAlIoc The server failed to allocate the requested resource or server 

memory. 

BadValue Some niimeric value falls outside the range of values accepted 

by the request. Unless a specific range is specified for an argu- 
ment, the full range defined by the argument's type is accepted. 
Any argument defined as a set of alternatives can generate this 
error. 

SEE ALSO 

XSetPointerMappingOXll) 
Xlib - C Language X Interface 
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NAME 

XChangePointerControl, XGetPointerControl - control pointer 
SYNTAX 

XChangePointerControl(^i^i!ay, dojiccel, dojhreshold, acceljtumeralor, 
acceljienominator, threshold) 
Display * display; " 
Bool dojiccel, dojhreshold) 
int acceljtumerator, accel_denomimtor; 
int threshold; 

XGetPointerControl((lisp%, acceljtumeratorj^etum, acceljienomimtorjetum, 
Ihresholdjetum) 
Display ^display; 

int *accel_numeratorjetum, *acceljienominatorj'etum; 
int *thresholdjetum; 

ARGUMENTS 

(uxeljienominator 

Specifies the denominator for the acceleration multiplier. 

accelJLeriomiriatorjreturn 

Returns the denominator for the acceleration multiplier. 

acceljtumerator Specifies the ntimerator for the acceleration multiplier. 

acceljiumeratorjreturn 

Returns the numerator for the acceleration multiplier. 

display Specifies the connection to the XwiN server. 

dojuxel Specifies a Boolean value that controls whether the values for 

the accel_numerator or accel_denominator are used. 

dojhreshold Specifies a Boolean value that controls whether the value for the 
threshold is used. 

threshold Specifies the acceleration threshold. 

ihresholdjetum Returns the acceleration threshold. 

DESCRIPTION 

The XChangePointerControl function defines how the pointing device moves. 
The acceleration, expressed as a fi-action, is a multiplier for movement. For exam- 
ple, specifying 3/1 means the pointer moves three times as fast as normal. The 
fraction may be rounded arbitrarily by the XwiN server. Acceleration only takes 
effect if the pointer moves more than threshold pixels at once and only applies to 
the amount beyond the value in the threshold argument. Setting a value to -1 
restores the default. The values of the do_accel and do_threshold arguments 
must be True for the pointer values to be set, or the parameters are imchanged. 
Negative values (other than -1) generate a Bad Value error, as does a zero value 
for the accel_denominator argument. 

XChangePointeiControl can generate a BadValue error. 
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The XGetPointerControl function returns the pointer's current acceleration multi- 
plier and acceleration threshold. 

DIAGNOSTICS 

BadValue Some numeric value falls outside the range of values accepted 

by the request. Unless a specific range is specified for an argu- 
ment, the full range defined by the argument's type is accepted. 
Any argument defined as a set of alternatives can generate this 
error. 

SEE ALSO 

Xlib - C Language X Interface 
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NAME 

XChangeSaveSet, XAddToSaveSet, XRemoveFromSaveSet - change a client's save 
set 

SYNTAX 

XChangeSaveSet (display, w, changejnode) 
Display * display; 
Window w, 
int changejnode; 

XAddToSaveSet (iisp%, w) 
Display * display; 
Window w; 

XRemoveFromSaveSet (<iisplay, w) 
Display *display; 
Window w; 

ARGUMENTS 

changejnode Specifies the mode. You can pass SetModelnsert or SetMo- 
deOelete. 

display Specifies the connection to the XwiN server. 

w Specifies the window that you want to add or delete fix>m the 

client's save-set. 

DESCRIPTION 

Depending on the specified mode, XChangeSaveSet either inserts or deletes the 
specified window from the client's save-set. The specified window must have 
been created by some other client, or a BadMatch error results. 

XChangeSaveSet can generate BadMatch, BadValue, and BadWindow errors. 

The XAddToSaveSet ftmction adds the specified window to the client's save-set. 
The specified window must have been created by some other client, or a Bad- 
Match error results. 

XAddToSaveSet can generate BadMatch and BadWindow errors. 

The XRemoveFromSaveSet function removes the specified window from the 
client's save-set. The specified window must have been created by some other 
client, or a BadMatch error results. 

XRemoveFromSaveSet can generate BadMatch and BadWindow errors. 
DIAGNOSTICS 

BadMatch Some argument or pair of arguments has the correct type and 
range but fails to match in some other way required by the 
request. 

BadValue Some nimieric value falls outside the range of values accepted 
by the request. Unless a specific range is specified for an argu- 
ment, the full range defined by the argument's type is accepted. 
Any argument defined as a set of alternatives can generate this 
error. 
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BadWindow A value for a Window argument does not name a defined Win- 
dow. 

SEE ALSO 

XReparentWindowOXll) 
Xlib - C Language X Interface 
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NAME 

XChangeWindowAttributes, XSetWindowBackground, XSetWindowBackground- 
Pixmap, XSetWindowBorder, XSetWindowBorderPixmap - change window attri- 
butes 

SYNTAX 

XChangeWindowAttributes((iispiay, w, valuemask, attributes) 
Display *display; 
Window w; 

unsigned long valuemask; 
XSetWindowAttributes ^attributes; 

XSetWindowBackground (<^isp%, w, background jnxel) 
Display *display; 
Window w; 

unsigned long background jrixel; 

XSetWindowBackgroundPixmap (<^isp%, w, background jnxmap) 
Display ^display; 
Window w; 

Pixmap background _pixmap; 

XSetWindowBorder ((iispky, w, border _pixeD 
Display * display; 
Window w; 

unsigned long border jnxel; 

XSetWindowBorderPixmap (iispZoy, w, border jnxmap) 
Display * display; 
Window w; 
Pixmap border jnxmap; 

ARGUMENTS 

attributes Specifies the structure from which the values (as specified by 

the value mask) are to be taken. The value mask should have 
the appropriate bits set to indicate which attributes have been 
set in the structure. 

backgroundjnxel Specifies the pixel that is to be used for the background. 

background jnxmap 

Specifies the background pixmap, PareiitRelative, or None. 

border jixel Specifies the entry in the colormap. 

borderjnxmap Specifies the border pixmap or CopyFroniPaient. 

display Specifies the connection to the XwiN server. 

valuemask Specifies which window attributes are defined in the attributes 

argument. This mask is the bitwise inclusive OR of the valid 
attribute mask bits. If valuemask is zero, the attributes are 
ignored and are not referenced. 
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w Specifies the window. 

DESCRIPTION 

Depending on the valuemask, the XChangeWindowAttributes function uses the 
window attributes in the XSetWindowAttributes structure to change the 
specified window attributes. Changing the background does not cause the win- 
dow contents to be changed. To repaint the window and its background, use 
XClearWindow. Setting the border or changing the background such that the 
border tile origin changes causes the border to be repainted. Changing the back- 
ground of a root window to None or ParentRelative restores the default back- 
ground pixmap. Changing the border of a root window to CopyFromParent 
restores the default border pixmap. Changing the win-gravity does not affect the 
current position of the window. Changing the backing-store of an obscured win- 
dow to WhenMapped or Always, or changing the backing-planes, backing-pixel, 
or save-under of a mapped window may have no immediate effect. Changing the 
colormap of a window (that is, defining a new map, not changing the contents of 
the existing map) generates a ColormapNotify event. Changing the colormap of 
a visible window may have no immediate effect on the screen because the map 
may not be installed (see XInstallColonnap). Changing the cursor of a root win- 
dow to None restores the default cursor. Whenever possible, you are 
encouraged to share colormaps. 

Multiple clients can select input on the same window. Their event masks are 
maintained separately. When an event is generated, it is reported to all interested 
clients. However, only one client at a time can select for Substruc- 
tureRedirectMask, ResizeRedirectMask, and ButtonPressMask. If a client 
attempts to select any of these event masks and some other client has already 
selected one, a BadAccess error results. There is only one do-not-propagate- 
mask for a window, not one per client. 

XChangeWindowAttributes can generate BadAccess, BadColor, BadCursor, 
BadMatch, BadPixmap, BadValue, and BadWindow errors. 

The XSetWindowBackground function sets the backgroimd of the window to the 
specified pixel value. Changing the background does not cause the window con- 
tents to be changed. XSetWindowBackground uses a pixmap of undefined size 
filled with the pixel value you passed. If you try to change the background of an 
InputOnly window, a BadMatch error results. 

XSetWindowBackground can generate BadMatch and BadWindow errors. 

The XSetWindowBackgioundPixmap function sets the background pixmap of 
the window to the specified pixmap. The backgroimd pixmap can immediately 
be freed if no further explicit references to it are to be made. If ParentRelative is 
specified, the background pixmap of the window's parent is used, or on the root 
window, the default background is restored. If you tiy to change the background 
of an InputOnly window, a BadMatch error results. If the background is set to 
None, the window has no defined background. 

XSetWindowBackgroundPixmap can generate BadMatch, BadPixmap, and 
BadWindow errors. 
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The XSetWindowBorder function sets the border of the window to the pixel 
value you specify. If you attempt to perform this on an InputOnly window, a 
BadMatdi error results. 

XSetWindowBorder can generate BadMatch and BadWindow errors. 

The XSetWindowBorderPixmap function sets the border pixmap of the window 
to the pixmap you specify. The border pixmap can be freed immediately if no 
further explicit references to it are to be made. If you spedfy CopyFiomPareiit, a 
copy of the parent window's border pixmap is used. If you attempt to perform 
this on an InputOnly window, a BadMatch error results. 

XSetWindowBorderPixmap can generate BadMatdi, BadPixmap, and BadWin- 
dow errors. 



DIAGNOSTICS 

BadAccess 

BadAccess 
BadColor 

BadCuisor 
BadMatch 



BadMatch 
BadPixmap 

BadValue 



BadWindow 



A client attempted to free a color map entry that it did not 
already allocate. 

A client attempted to store into a read-only color map entry. 

A value for a Colormap aigument does not name a defined 
Colormap. 

A value for a Cursor argument does not name a defined Cursor. 

Some argtunent or pair of arguments has the correct type and 
range but fails to match in some other way required by the 
request. 

An InputOnly window locks this attribute. 

A value for a Pixmap aigument does not name a defined Pix- 
map. 

Some numeric value falls outside the range of values accepted 
by the request. Unless a specific range is specified for an argu- 
ment, the full range defined by the argument's type is accepted. 
Any argument defined as a set of alternatives can generate this 
error. 

A value for a Window argument does not name a defined Win- 
dow. 



SEE ALSO 

XConfigureWindowOXll), 

XCreateWindowOXll), 

XDestroyWindowOXll), 

XMapWindowOXll), 

XRaiseWindowOXll), 

XUnmapWindowOXll) 

Xlib - C Language X Interface 
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NAME 

XCIear Area, XClearWindow - clear area or window 
SYNTAX 

XClearArea(iisp%/ w, x, y, vMth, height, exposures) 
Display *dispiajf; 
Window w; 
int X, y; 

unsigned int imdth, height; 
Bool exposures; 

XClearWindow(i/sp%, w) 
Display * display; 
Window w; 

ARGUMENTS 

display 

exposures 
w 

zvidth 
height 

X 

y 



DESCRIPTION 

The XClearArea function paints a rectangular area in the specified window 
according to the specified dimensions with the window's background pixel or 
pixmap. The subwindow-mode effectively is ClipByChildren. If width is zero, 
it is replaced with the current width of the window minus x. If height is zero, it 
is replaced with the current height of the window minus y. If the window has a 
defined background tile, the rectangle clipped by any children is filled with this 
tile. If the window has background None, the contents of the window are not 
changed. In either case, if exposures is True, one or more Expose events are gen- 
erated for regions of the rectangle that are either visible or are being retained in a 
backing store. If you specify a window whose class is InputOnly, a BadMatch 
error results. 

XClearArea can generate BadMatch, BadValue, and BadWindow errors. 

The XClearWindow function clears the entire area in the specified window and is 
equivalent to XClearArea (display, w, 0, 0, 0, 0, False). If the window has a 
defined background tile, the rectangle is tiled with a plane-nuisk of all ones and 
GXcopy function. If the window has background None, the contents of the win- 
dow are not changed. If you specify a window whose class is InputOnly, a Bad- 
Match error results. 



Specifies the connection to the XwiN server. 

Specifies a Boolean value that indicates if Expose events are to 
be generated. 

Specifies the window. 

Specify the width and height, which are the dimensions of the 
rectangle. 

Specify the x and y coordinates, which are relative to the origin 
of the window and specify the upper-left comer of the rectan- 
gle. 
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can generate BadMatch and BadWindow errors. 

An InputOnly window is used as a Drawable. 

Some numeric value falls outside the range of values accepted 
by the request. Unless a specific range is specified for an argu- 
ment, the full range defined by the argument's type is accepted. 
Any argument defined as a set of alternatives can generate this 
error. 

BadWindow A value for a Window argument does not name a defined Win- 
dow. 

SEE ALSO 

XCopyAreaOXll) 

Xlib - C Language X Interface 



XClearWindow 

DIAGNOSTICS 

BadMatch 

BadValue 
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NAME 

XConfigureWindow, XMoveWindow, XResizeWindow, XMoveResizeWindow, 
XSetWindowBorderWidth - configtire windows 

SYNTAX 

XConfigiireWindow(iisplfly, w, value jnask, values) 
Display * display; 
Window w; 

unsigned int value jnask; 
XWindowChanges *values; 

XMoveWindow(display, w, x, y) 
Display * display; 
Window w; 
int X, y; 

XResizeWindow(^isp2^, w, zoidth, height) 
Display ^display; 
Window w; 

unsigned int zmdih, height; 

XMoveReslzeWindow (display, w, x, y, zmdth, height) 
Display ^display; 
Window w; 
int X, y; 

unsigned int tmdth, height; 

XSetWindowBorderWidth (izsploy, w, zoidth) 
Display ^display; 
Window w; 
unsigned int width; 

ARGUMENTS 

display Specifies the connection to the XwiN server. 

value jmsk Specifies which values are to be set using information in the 
values structure. This mask is the bitwise inclusive OR of the 
valid configure window values bits. 

values Specifies a pointer to the XWindowChanges structure. 

w Specifies the window to be reconfigured, moved, or resized.. 

vndth Specifies the width of the window border. 

width 

height Specify the width and height, which are the interior dimensions 

of the window. 

X 

y Specify the x and y coordinates, which define the new location 

of the top-left pixel of the window's border or the window itself 
if it has no border or define the new position of the window 
relative to its parent. 
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DESCRIPTION 

The XConfigureWindow function uses the values specified in the XWin- 
dowChanges structure to reconfigure a window's size, position, border, and 
stacking order. Values not specified are taken from the existing geometry of the 
window. 

If a sibling is specified without a stack mode or if the window is not actually a 
sibling, a BadMatch error results. Note that the computations for Bottomlf, 
Toplf , and Opposite are performed with respect to the window's final geometry 
(as controlled by the other arguments passed to XConfigureWindow), not its ini- 
tial geometry. Any backing store contents of the window, its inferiors, and other 
newly visible windows are either discarded or changed to reflect the current 
screen contents (depending on the implementation). 

XConfigureWindow can generate BadMatch, BadValue, and BadWindow 
errors. 

The XMoveWindow function moves the specified window to the specified x and 
y coordinates, but it does not change the window's size, raise the window, or 
change the mapping state of the window. Moving a mapped window may or 
may not lose the window's contents depending on if the window is obscured by 
nonchildren and if no backing store exists. If the contents of the window are lost, 
the XwiN server generates &cpose events. Moving a mapped window generates 
Expose events on any formerly obscured windows. 

If the override-redirect flag of the window is False and some other client has 
selected SubstnictureRedirectMask on the parent, the XwiN server generates a 
ConfigureRequest event, and no further processing is performed. Otherwise, the 
window is moved. 

XMoveWindow can generate a BadWindow error. 

The XResizeWindow function changes the inside dimensions of the specified 
window, not including its borders. TTiis function does not change the window's 
upper-left coordinate or the origin and does not restack the window. Changing 
the size of a mapped window may lose its contents and generate Expose events. 
If a mapped window is made smaller, changing its size generates Expose events 
on windows that the mapped window formerly obscured. 

If the override-redirect flag of the window is False and some other client has 
selected SubstnictureRedirectMask on the parent, the XwiN server generates a 
ConfigureRequest event, and no further processing is performed. If either width 
or height is zero, a BadValue error results. 

XResizeWindow can generate BadValue and BadWindow errors. 

The XMoveResizeWindow function changes the size and location of the specified 
window without raising it. Moving and resizing a mapped window may gen- 
erate an Expose event on the window. Depending on the new size and location 
parameters, moving and resizing a window may generate Expose events on win- 
dows that the window formerly obscured. 
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If the override-redirect flag of the window is False and some other client has 
selected SubstructureRedirectMask on the parent, the XwiN server generates a 
ConfigureRequest event, and no further processing is performed. Otherwise, the 
window size and location are changed. 

XMoveResizeWindow can generate BadValue and BadWindow errors. 

The XSetWindowBorderWidth function sets the specified window^s border width 
to the specified width. 

XSetWindowBorderWidth can generate a BadWindow error. 
DIAGNOSTICS 

BadMatch An InputOnly window is used as a Drawable. 

BadMatch Some argument or pair of arguments has the correct type and 
range but fails to match in some other way required by the 
request. 

BadValue Some numeric value falls outside the range of values accepted 
by the request. Unless a specific range is specified for an argu- 
ment, the full range defined by the argument's type is accepted. 
Any argument defined as a set of alternatives can generate this 
error. 

BadWindow A value for a Window argument does not name a defined Win- 
dow. 

SEE ALSO 

XChangeWindowAttributesOXll), 

XCreateWindowOXll), 

XDestroyWindowOXll), 

XMapWindowOXll), 

XRaiseWindowOXll), 

XUnmapWindowOXll) 

Xlib - C Language X Interface 



10/89 



Page 3 



XCopyArM (3X1 1 } XCopyArea (3X1 1 ) 



NAME 

XCopyArea, XCopyPlane - copy areas 
SYNTAX 

XCopyAresiidisphy, src, dest, gc, srcjc, srcjf, width, height, destjc, destjf) 
EHsplay *display; 
Drawable src, dest; 
GC gc; 

int src x, srcj/; 
unsigned int width, height; 
int destjc, destjf; 

XQovy?[dine{disphy, src, dest, gc, srcjc, srcj/, width, height, destjc, destjf, plane) 
EHsplay *display; 
Drawable src, dest; 
GCgc; 

int srcjc, srcjf; 
unsigned int width, height; 
int destjc, destjf; 
unsigned long plane; 

ARGUMENTS 

destjc 

destjf Specify the x and y coordinates, which are relative to the origin 

of the destination rectangle and specify its upper-left comer. 

display Specifies the connection to the XwiN server. 

gc Specifies the GC. 

plane Specifies the bit plane. You must set exactly one bit to 1. 

src 

dest Specify the source and destination rectangles to be combined. 

srcjc 

srcjf Specify the x and y coordinates, which are relative to the origin 

of the source rectangle and specify its upper-left comer. 

width 

height Specify the width and height, which are the dimensions of both 

the source and destination rectangles. 

DESCRIPTION 

The XCopyArea function combines the specified rectangle of src with the 
specified rectangle of dest. The draWables must have the same root and depth, or 
a BadMatdi error results. 

If regions of the source rectangle are obscured and have not been retained in 
backing store or if regions outside the boundaries of the source drawable are 
specified, those regions are not copied. Instead, the following occurs on all 
corresponding destination regions that are either visible or are retained in backing 
store. If the destination is a window with a background other than None, 
corresponding regions of the destination are tiled with that background (with 
plane-mask of all ones and GXcopy function). Regardless of tiling or whether 
the destination is a window or a pixmap, if graphics-exposures is True, then 
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GraphicsExpose events for all corresponding destination regions are generated. 
If graphics-expostires is True but no GraphicsExpose events are generated, a 
NoExpose event is generated. Note that by default graphics-exposures is True in 
new GCs. 

This function uses these GC components: function, plane-mask, subwindow- 
mode, graphics-exposures, clip-x-origin, clip-y-origin, and clip-mask. 

XCopyAiea can generate BadDiawable, BadGC, and BadMatch errors. 

The XCopyPlane function uses a single bit plane of the specified source rectangle 
combined with the specified GC to modify the specified rectangle of dest. The 
drawables must have the same root but need not have the same depth. If the 
drawables do not have the same root, a BadMatch error results. If plane does 
not have exactly one bit set to 1 and the values of planes must be less than 2 ^, 
where n is the depth of src, a BadValue error results. 

Effectively, XCopyPlane forms a pbcmap of the same depth as the rectangle of 
dest and with a size specified by the source region. It uses the 
foreground/background pixels in the GC (foreground everywhere the bit plane in 
src contains a bit set to 1, backgroimd everywhere the bit plane in src contains a 
bit set to 0) and the equivalent of a Copy Area potocol request is performed with 
all the same exposure semantics. This can also be thought of as using the 
specified region of the source bit plane as a stipple with a fill-style of FiliOpa- 
queStippled for filling a rectangular area of the destination. 

This function uses these GC components: function, plane-mask, fbregroimd, back- 
ground, subwindow-mode, graphics-exposures, clip-x-origin, clip-y-origin, and 
clip-mask. 

XCopyPlane can generate BadDrawable, BadGC, BadMatch, and BadValue 
errors. 



BadDiawable A value for a Drawable argument does not name a defined 
Window or Bxmap. 



DIAGNOSTICS 



BadGC 



A value for a GContext argument does not name a defined 
GContext. 

An InputOnly window is used as a Drawable. 



BadMatch 
BadMatch 



Some argument or pair of arguments has the correct type and 
range but ^ils to match in some other way required by the 
request. 



BadValue 



Some numeric value falls outside the range of values accepted 
by the request. Unless a specific range is specified for an argu- 
ment, the full range defined by the argtmient^s type is accepted. 
Any argument defined as a set of alternatives can generate this 
error. 



SEE ALSO 



XClearAreaOXll) 

Xlib - C Language X Interface 
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NAME 

XCreateColormap, XCopyColormapAndFree^ XFreeColormap, XSetWindowColor- 
map - create, copy, or destroy colormaps 

SYNTAX 

Colormap XCreateColormap (ixsp2ay, w, visual, alloc) 
Display * display; 
Window w; 
Visual *visual; 
int alloc; 

Colormap XCopyColormapAndFree (display, colormap) 
Display ^display; 
Colormap colormap; 

XFreeColormap (t/f^ky, colormap) 
Display ^display; 
Colormap colormap; 

XSetWindowColormapCiispiiy, w, colormap) 
Display * display; 
Window w; 
Colormap colormap; 

ARGUMENTS 

alloc Specifies the colormap entries to be allocated. You can pass 

AUocNone or AUocAll. 

colormap Specifies the colormap that you want to create, copy, set, or 

destroy. 

display Specifies the connection to the XwiN server. 

visual Specifies a pointer to a visual tj^ supported on the screen. If 

the visual type is not one supported by the screen, a BadMatch 
error results. 

w Specifies the window for which you want to create or set a 

colormap . 

DESCRIPTION 

The XCreateColormap function creates a colormap of the specified visual tyipe for 
the screen on which the specified window resides aiid returns the colormap ID 
associated with it. Note that the specified window is only used to determine the 
screen. 

The initial values of the colormap entries are undefined for the visual classes 
Grayscale, PseudoColor, and DirectColor. For StaticGiay, StaticColor, and 
TnieColor, the entries have defined values, but those values are specific to the 
visual and are not defined by X. For StaticGray, StaticColor, and TrueColor, 
alloc must be AllocNone, or a BadMatch error results. For the other visual 
classes, if alloc is AllocNone, the colormap initially has no allocated entries, and 
clients can allocate them. For information about the visual types, see section 3.1, 
X/i2? — C Language X Interface. 
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If alloc is AllocAU, the entire colormap is allocated writable. The initial values of 
all allocated entries are undefined. For Grayscale and PseudoColor, the effect is 
as if an XAllocColoiCells call rettimed all pixel values from zero to N ~ 1, where 
N is the colormap entries value in the specified visual. For DiredColor, the 
effect is as if an XAlIocColorPIanes call returned a pixel value of zero and 
red_mask, green_mask, and blue^mask values containing the same bits as the 
corresponding masks in the specified visual. However, in all cases, none of these 
entries can be freed by using XFreeColors. 

XCreateColoimap can generate BadAlloc, BadMatdi, BadValue, and BadWin- 
dow errors. 

The XCopyColonnapAndFree function creates a colormap of the same visual 
type and for the same screen as the specified colonnap and returns the new color- 
map ID. It also moves all of the client's existing allocation from the specified 
colormap to the new colormap with their color values intact and their read-only 
or writable characteristics intact and frees those entries in the specified colormap. 
Color values in other entries in the new colormap are undefined. If the specified 
colormap was created by the client with alloc set to AUocAll, the new colormap 
is also created with AllocAU, all color values for all entries are copied from the 
specified colormap, and then all entries in the specified colormap are freed. If the 
specified colormap was not created by the client with AllocAU, the allocations to 
oe moved are all those pixels and planes that have been allocated by the client 
using XAUocColor, XAUocNamedColor, XAUocColorCeUs, or XAUocColor- 
Planes and that have not been freed since they were allocated. 

XCopyColonnapAndFree can generate BadAUoc and BadColor errors. 

The XFreeColormap ftmction deletes the association between the colormap 
resource ID and the colormap and frees the colormap storage. However, this 
function has no effect on the defoult colormap for a screen. If the specified color- 
map is an installed map for a screen, it is uninstalled (see XUninstaUColormap). 
If the specified colormap is defined as the colormap for a window (by 
XCreateWindow, XSetWindowColonnap, or XChangeWindowAttributes), 
XFreeColonnap changes the colormap associated with the window to None and 
generates a ColonnapNotify event. X does not define the colors displayed for a 
window with a colormap of None. 

XFreeColormap can generate a BadColor error. 

The XSetWindowColonnap fimction sets the specified colormap of the specified 
window. The colormap must have the same visual type as the window, or a 
BadMatch error results. 

XSetWindowColonnap can generate BadColor, BadMatch, and BadWindow 

errors. 

DIAGNOSTICS 

BadAUoc The server failed to allocate the requested resource or server 

memory. 

BadColor A value for a Colormap argument does not name a defined 

Colormap. 
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BadMatch An InputOnly window is used as a Drawable. 

BadMatdi Some argument or pair of arguments has the correct type and 
range but fails to match in some other way required by the 
request. 

BadValue Some numeric value falls outside the range of values accepted 

by the request. Unless a specific range is specified for an argu- 
ment, the full range defined by the argument's type is accepted. 
Any argiiment defined as a set of alternatives can generate this 
error. 

BadWindow A value for a Window argument does not name a defined Win- 
dow. 

SEE ALSO 

XAUocColorOXll), 

XQueryColorOXll), 

XStoreColors(3Xll) 

Xlib - C Language X Interface 
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NAME 

XCreateFontCursor, XCreatePixmapCursor, XCreateGlyphCursor - create ctirsors 

SYNTAX 

#indude <Xll/cursorf6nt.h> 

Cursor XCreateFontCursor(iisp2ay, shape) 
Display *disphy; 
unsigned int shape; 

Cursor XCreatePixmapCursor(if^%, source, mask, foreground jcolor, 
background johr, x, y) 
Display "^display; 
Pixmap source) 
Pixmap mask) 
XColor *foregroundjx>lor) 
XColor *backgroundj:olor) 
unsigned int x, y; 

Cursor XCreateGlyphCursor((lx^%, source Jont, maskjont, source jhar, maskjhar, 
foreground jx>lor, background jx>br) 
Display * display) 
Font source Jont, maskjont) 
unsigned int source jhar, maskjdtar) 
XColor *foreground_color) 
XColor *backgroundjcolor) 

ARGUMENTS 

background j:olor Specifies the RGB values for the background of the source. 

display Specifies the connection to the XwiN server. 

foreground jx)lor Specifies the RGB values for the foreground of the source. 

mask Specifies the cursor's source bits to be displayed or None. 

maskj:har Specifies the gl)^h character for the mask. 

maskjont Specifies the font for the mask gl3^h or None. 

shape Specifies the shape of the cursor. 

source Specifies the shape of the source cursor. 

source jJuir Specifies the character glyph for the source. 

source Jont Specifies the font for the source gl3^h. 

X 

y Specify the x and y coordinates, which indicate the hotspot rela- 

tive to the source's origin. 

DESCRIPTION 

X provides a set of standard cursor shapes in a special font named cursor. Appli- 
cations are encouraged to use this interface for their cursors because the font can 
be customized for the individual display type. The shape aigument specifies 
which gl3^h of the standard fonts to use. 
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The hotspot comes from the information stored in the cursor font. The initial 
colors of a cursor are a black foreground and a white backgrotmd (see XRecolor- 
Cursor). 

XCreateFonlCtirsor can generate BadAlloc and BadValue errors. 

The XCreatePixmapCursor function creates a cursor and returns the cursor ID 
associated with it. The foreground and background RGB values must be 
specified using foregroimd color and background_color, even if the XwiN server 
only has a StaticGray or GrayScale screen. The foreground color is used for the 
pixels set to 1 in the source, and the background color is used for the pixels set to 
0. Both source and mask, if specified, must have depth one (or a BadMatch error 
results) but can have any root. The mask argument defines the shape of the cur- 
sor, llie pixels set to 1 in the mask define which source pixels are displayed, and 
the pixels set to 0 define which pixels are ignored. If no mask is given, all pixels 
of the source are displayed. The mask, if present, must be the same size as the 
pbcmap defined by the source argument, or a BadMatch error results. The 
hotspot must be a point within the source, or a BadMatch error results. 

The components of the cursor can be transformed arbitrarily to meet display limi- 
tations. The pixmaps can be freed immediately if no further explicit references to 
them are to be made. Subsequent drawing in the source or mask pixmap has an 
undefined effect on the cursor. The XwiN server might or might not make a copy 
of the pixmap. 

XCreatePixmapCursor can generate BadAlloc and BadPixmap errors. 

The XCreateGlyphCursor function is similar to XCreatePixmapCursor except 
that the source and mask bitmaps are obtained from the specified font gl3^hs. 
The sourcejchar must be a defined glyph in source_font, or a BadValue error 
results. If mask_font is given, mask_char must be a defined glyph in mask_font, 
or a BadValue error results. The mask_font and character are optional. The ori- 
gins of the sourcejchar and mask_char (if defined) glyphs are positioned coin- 
cidently and define the hotspot. The sourcejchar and mask_char need not have 
the same bounding box metrics, and there is no restriction on the placement of 
the hotspot relative to the bounding boxes. If no maskjchar is given, all pixels of 
the source are displayed. You can free the fonts immediately by calling 
XFreeFont if no further explicit references to them are to be made. 

For 2-b5^e matrix fonts, the 16-bit value should be formed with the bytel member 
in the most-significant byte and the byte2 member in the least-significant byte. 

XCreateGlyphCuisor can generate BadAlloc, BadFont, and BadValue errors. 

DIAGNOSTICS 

BadAlloc The server failed to allocate the requested resource or server 

memory. 

BadFont A value for a Font or GCbntext argument does not name a 

defined Font. 

BadMatch Some aigument or pair of arguments has the correct type and 
range but fails to match in some other way required by the 
request. 
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BadPixmap A value for a Bxmap argument does not name a defined Pix- 
map. 

BadValue Some numeric value falls outside the range of values accepted 
by the request. Unless a specific range is specified for an argu- 
ment, the full range defined by the argument's type is accepted. 
Any argument defined as a set of alternatives can generate this 
error. 

SEE ALSO 

XDefineCursorOXll), 
XRecolorCursorOXll) 
Xlib - C Language X Interface 
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NAME 

XCreateGC, XCopyGQ XChangeGQ XFreeGC, XGContextFromGC ~ create or 
free graphics contexts 

SYNTAX 

GC XCreateGC(^ispky, d, valuemask, values) 
Display ^display; 
Drawable d; 

unsigned long valuemask; 
XGCValues *values; 

XCopyCXl(display, src, valuemask, dest) 
EHsplay *display; 
GC src, dest ; 

unsigned long valuemask; 

XChangeGCidisplay, gc, valuemask, values) 
Display * display; 
GC gc; 

unsigned long valuemask; 
XGCValues * values; 

XFreeGC(display, gc) 
Display *display; 
GCgc; 

GContext XGContextFromGC(gc) 
GC^; 

ARGUMENTS 

d Specifies the drawable. 

dest Specifies the destination GC. 

display Specifies the connection to the XwiN server. 

gc Specifies the GC. 

src Specifies the con\ponents of the source GC. 

valuemask Specifies which components in the GC are to be set, copied, or 

changed . This argument is the bitwise inclusive OR of one or 
more of the valid GC component mask bits. 

values Specifies any values as specified by the valuemask. 

DESCRIPTION 

The XCreateGC function creates a graphics context and returns a GC. The GC 
can be used with any destination drawable having the same root and depth as the 
specified drawable. Use with other drawables restdts in a BadMatdi error. 

XCreateGC can generate BadAlloc, BadDrawable, BadFont, BadMatdi, BadPix- 
map, and BadValue errors. 

The XCopyGC function copies the specified components from the source GC to 
the destination GC. The source and destination GCs must have the same root 
and depth, or a BadMatch error results. The valuemask specifies which com- 
ponent to copy, as for XCreateGC. 
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XCopyGC can generate BadAUoc, BadGC, and BadMatdi errors. 

The XQiangeGC function changes the components specified by valuemask for 
the specified GC. The values argument contains the values to be set. The values 
and restrictions are the same as for XCreateGC. Qianging the clip-mask over- 
rides any previous XSetClipRectangles request on the context. Changing the 
dash-offset or dash-list overrides any previous XSetDashes request on the con- 
text. The order in which components are verified and altered is server- 
dependent. If an error is generated, a subset of the components may have been 
altered. 

XChangeGC can generate BadAlloc, BadFont, BadGC, BadMatch, BadPixmap, 
and BadValue errors. 

The XFreeGC function destroys the specified GC as well as all the associated 
storage. 

XFreeGC can generate a BadGC error. 
DIAGNOSTICS 

BadAlloc The server failed to allocate the requested resource or server 

memory. 

BadDrawable A value for a Drawable argument does not name a defined 
Window or Pixmap. 

BadFont A value for a Font or GContext argument does not name a 

defined Font. 

BadGC A value for a GContext argument does not name a defined 

GContext. 

BadMatch An InputOnly window is used as a Drawable. 

BadMatch Some argument or pair of argtiments has the correct type and 
range but fails to match in some other way required by the 
request. 

BadPixmap A value for a Pixmap argument does not name a defined Pix- 
map. 

BadValue Some ntimeric value falls outside the range of values accepted 
by the request. Unless a specific range is specified for an argu- 
ment, the full range defined by the argument's type is accepted. 
Any argument defined as a set of alternatives can generate this 
error. 

SEE ALSO 

XQueryBestSize{3Xll), 

XSetArcMode(3Xll), 

XSetaipQrigin(3Xll), 

XSetFillStyle{3Xll), 

XSetFont(3Xll), 

XSetLineAttributes(3Xll), 

XSetState(3Xll), 

XSetTile(3Xll) 

XHb - C Language X Interface 
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NAME 

XCreatdmage, XGetPixel, XPutPixel, XSublmage, XAddPixel, XDestroylmage - 
image utilities 

SYNTAX 

Xlmage *XCreateImage (iispky, visual, depth, format, offset, data, tvidth, height, 
bitmap jHid, bytes jperjine) 

Display * display, 
Visual *visual; 
unsigned int depth; 
int format; 
int offset; 
char *data; 
unsigned int xaidth; 
unsigned int height; 
int bitmap jfod; 
int bytes Jperjine; 

unsigned long XGetPixel(xxmag^, x, y) 
Xlmage *ximage; 
int x; 
inty; 

int XPuiFixeliximage, x, y, pixel) 
Xlmage *ximage; 
int x; 
int y; 

unsigned long pixel; 

Xlmage *XSubImage(;dmag^, x, y, subimagejvidth, subimagejteigkt) 
Xlmage *ximage; 
int x; 
int y; 

unsigned int subimagejvidth; 
unsigned int suJnmageJteight; 

XAddPixel(xim^ig€, value) 
Xlmage *ximage; 
long value; 

int XDestroylmage (xfmage) 
Xlmage *ximage; 

ARGUMENTS 

bitmap jxid Specifies the quantum of a scanline (8, 16, or 32). In other 
words, the start of one scanline is separated in client memory 
from the start of the next scanline by an integer multiple of this 
many bits. 

bytesjjerjine Specifies the number of bytes in the client image between the 
start of one scanline and the start of the next. 
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dutu 


Sisecifies a tx)inter to the imaffe data 


depth 


Specifies the depth of the image. 


display 


Specifies the connection to the XwiN server. 


fonnut 


Specifies the fomidt for the image. You can pass XYBifmap/ 




XYPixmap, or ZPixmap. 


height 


Specifies the height of the image, in pixels. 


offset 


Specifies the nimiber of pixels to ignore at the beginning of the 




scanline. 


pixel 


Specifies the new pixel value. 


subiifuige_height 


Specifies the height of the new subimage, in pixels. 


siibimagejundth 


Specifies the width of the new subimaee, in pixels. 


value 


Specifies the constant value that is to be added. 


visual 


Specifies a pointer to the visual. 


vndth 


Specifies the width of the image, in pixels. 


ximage 


Specifies a pointer to the image. 


X 

y 


Specify the x and y coordinates. 



DESCRIPTION 

The XCreatelmage function allocates the memory needed for an Ximage struc- 
ture for the specified display but does not allocate space for the image itself. 
Rather, it initializes the structure byte-order, bit-order, and bitmap-unit values 
from the display and returns a pointer to the Ximage structure. The red, green, 
and blue mask values are defined for Z format images only and are derived from 
the Visual structure passed in. Other values also are passed in. The offset per- 
mits the rapid displaying of the image without requiring each scanline to be 
shifted into position. If you pass a zero value in bytes_per_line, Xlib assumes 
that the scanlines are contiguous in memory and calculates the value of 
bytes_perjine itself. 

Note that when the image is created using XCreatelmaii, XGetlmage, or 
XSublmage, the destroy procedure that the XDestioylmage function calls frees 
both the image structure and the data pointed to by the image structure. 

The basic functions used to get a pixel, set a pixel, create a subimage, and add a 
constant offset to a Z format image are defined in the image object. The func- 
tions in this section are really macro invocations of the functions in the image 
object and are defined in <X11/Xutil.h>. 

The XGetPixel function returns the specified pixel from the named image. The 
pixel value is returned in normalized format (that is, the least-significant byte of 
the long is the least-significant byte of the pixel). The image must contain the x 
and y coordinates. 
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The XPutPixel function overwrites the pixel in the named image with the 
specified pixel value. The input pixel value must be in normalized format (that 
is, the least-significant byte of the long is the least-significant byte of the pixel). 
The image must contain the x and y coordinates. 

The XSublmage function creates a new image that is a subsection of an existing 
one. It allocates the memory necessary for the new Xlmage structure and returns 
a pointer to the new image. The data is copied from the source image, and the 
image must contain the rectangle defined by x, y, subimage_width, and 
subimage_height. 

The XAddPixel function adds a constant value to every pixel in an image. It is 
useful when you have a base pixel value from allocating color resources and need 
to manipulate the image to that form. 

The XDestroylmage function deallocates the memory associated with the Xlm- 
age structure. 

SEE ALSO 

XPutlmageOXll) 

Xlib ~ C Language X Interface 
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NAME 

XCreatePixmap, XFreePixmap - create or destroy pixmaps 
SYNTAX 

Pixmap XCreateFixmap(display, d, xmdth, height, depth) 
Display * display) 
Drawable d; 

unsigned int width, height; 
unsigned int depth; 

XFreeFixmapidisphy, pixmap) 
Display * display; 
Pixmap pixmap; 

ARGUMENTS 

d Specifies which screen the pixmap is created on. 

depth Specifies the depth of the pixmap. 

display Specifies the connection to the XwiN server. 

pixmap Specifies the pixmap. 

width 

height Specify the width and height, which define the dimensions of 

the pixmap. 

DESCRIPTION 

The XCreatePixmap function creates a pixmap of the width, height, and depth 
you specified and returns a pixmap ID that identifies it. It is vadid to pass an 
InputOnly window to the drawable argument. The width and height arguments 
must be nonzero, or a BadValue error results. The depth argument must be one 
of the depths supported by the screen of the specified drawable, or a BadValue 
error results. 

The server uses the specified drawable to determine on which screen to create the 
pixmap. The pixmap can be used only on this screen and only with other draw- 
ables of the same depth (see XCopyPlane for an exception to this rule). The ini- 
tial contents of the pixmap are undefined. 

XCreatePixmap can generate BadAlloc, BadDiawable, and BadValue errors. 

The XFreePixmap function first deletes the association between the pixmap ID 
and the pixmap. Then, the XwiN server frees the pixmap storage when there are 
no references to it. The pixmap should never be referenced again. 

XFreePixmap can generate a BadPixmap error. 

DIAGNOSTICS 

BadAlloc The server failed to allocate the requested resource or server 

memory. 

BadDrawable A value for a Drawable argument does not name a defined 
Window or Pixmap. 
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BadPixmap A value for a Pixmap argument does not name a defined Pix- 
map. 

BadValue Some numeric value falls outside the range of values accepted 

by the request. Unless a specific range is specified for an argu- 
ment, the full range defined by the argument's type is accepted. 
Any argument defined as a set of alternatives can generate this 
error. 

SEE ALSO 

Xlib - C Language X Interface 
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NAME 

XCreateR^on, XSetRegion, XDestroyRegion - create or destroy regions 

SYNTAX 

Region XCreateRegionO 

XSetRegion (^ispky, gc, r) 
Display *dtspUy; 
GC gc; 
Region r; 

XDestroyRegion(r) 
Region r; 

ARGUMENTS 

display Specifies the connection to the XwiN server. 

gc Specifies the GC. 

r Specifies the region. 

DESCRIPTION 

The XCreateRegion function creates a new empty region. 

The XSetRegion function sets the clip-mask in the GC to the specified region. 
Once it is set in the GC, the region can be destroyed. 

The XDestroyRegion function deallocates the storage associated with a specified 
region. 

SEE ALSO 

XEmptyRegionOXll), 
XIntersectRegionOXll) 
Xlib - C Language X Interface 
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NAME 

XCreateWindow, XCreateSimple Window - create windows 
SYNTAX 

Window XCreateWindow(<^tspky, parent, x, y, width, height, border jvidth, depth, 
class, visual, valuemask, attrimtes) 
Display * display; 
Window parent; 
int X, y; 

unsigned int width, height; 
unsigned int border jmdth; 
int depth; 

unsigned int class; 

Visual *visual 

unsigned long valuemask; 

XSetWindowAttributes ^attributes; 

Window XCreateSimpleWindow(iisp%, parent, x, y, width, height, border jwidth, 
border, background) 

Display * display; 
Window parent; 
int X, y; 

unsigned int width, height; 
unsigned int border jwidth; 
unsigned long border; 
unsigned long background; 

ARGUMENTS 

attributes Specifies the structure from which the values (as specified by 

the value mask) are to be taken. The value mask should have 
the appropriate bits set to indicate which attributes have been 
set in the structure. 

background Specifies the background pixel value of the window. 



border Specifies the border pixel value of the window. 

border jwidth Specifies the width of the created window's border in pixels. 

class Specifies the created window's class. You can pass InputCXit- 

put, InpulOnly, or CopyFromParent. A class of CopyFiom- 
Parent means the class is taken from the parent. 

depth Specifies the window's depth. A depth of CopyFromParent 

means the depth is taken from the parent. 

display Specifies the connection to the XwiN server. 

parent Specifies the parent window. 

valuemask Specifies which window attributes are defined in the attributes 

argument. This mask is the bitwise inclusive OR of the valid 
attribute mask bits. If valuemask is zero, the attributes are 
ignored and are not referenced. 
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visual 



Specifies the visual type. A visual of CopyFromPaient means 
the visual type is taken from the parent. 



width 
height 



Specify the width and height, which are the created window's 
inside dimensions and do not include the created window's 
borders. 



X 



y 



Specify the x and y coordinates, which are the top-left outside 
corner of the window's borders and are relative to the inside of 
the parent window's borders. 



DESCRIPTION 

The XCreateWindow function creates an unmapped subwindow for a specified 
parent window, returns the window ID of the created window, and causes the 
XwiN server to generate a CreateNotify event. The created window is placed on 
top in the stacking order with respect to siblings. 

The border_width for an InputOnly window must be zero, or a BadMatch error 
results. For class InputOutput, the visual type and depth must be a combination 
supported for the screen, or a BadMatch error results. The depth need not be 
the same as the parent, but the parent must not be a window of class InputOnly, 
or a BadMatch error results. For an InputOnly window, the depth must be 
zero, and the visual must be one supported by the screen. If either condition is 
not met, a BadMatch error results. The parent window, however, may have any 
depth and class. If you specify any invalid window attribute for a window, a 
BadMatch error results. 

The created window is not yet displayed (mapped) on the user's display. To 
display the window, call XMap Window. The new window initially uses the 
same cursor as its parent. A new cursor can be defined for the new window by 
calling XDefineCursor. The window will not be visible on the screen unless it 
and all of its ancestors are mapped and it is not obscured by any of its ancestors. 

XCreateWindow can generate BadAUoc BadColor, BadCursor, BadMatch, Bad- 
Pixmap, BadValue, and BadWindow errors. 

The XCreateSimpleWindow function creates an unmapped InputOutput 

subwindow for a specified parent window, returns the window ID of the created 
window, and causes the XwiN server to generate a CreateNotify event. The 
created window is placed on top in the stacking order with respect to siblings. 
Any part of the window that extends outside its parent window is clipped. The 
border_width for an InputOnly window must be zero, or a BadMatch error 
results. XCreateSimpleWindow inherits its depth, class, and visual from its 
parent. All other window attributes, except background and border, have their 
default values. 

XCreateSimpleWindow can generate BadAUoc, BadMatch, BadValue, and 
BadWindow errors. 



Page 2 10/89 



XCreatoWlndow(3X11) 



XCreateWindow(3X11) 



DIAGNOSTICS 

BadAUoc 



The server failed to allocate the requested resource or server 
memory. 



BadColor 



A value for a Colormap a]*gument does not name a defined 
Colormap. 



BadCursor 
BadMatch 
BadMalch 



Some argument or pair of arguments has the correct type and 
range but fails to match in some other way required by the 
request. 



The values do not exist for an InputOnly window. 



A value for a Cursor argument does not name a defined Cursor. 



BadPixmap 



A value for a Pixmap aigument does not name a defined Bx- 
map. 



BadValue 



Some numeric value falls outside the range of values accepted 
by the request. Unless a specific range is specified for an argu- 
ment, the full range defined by the argument's type is accepted. 
Any argimient defined as a set of alternatives can generate this 
error. 



BadWindow A value for a Window argument does not name a defined Win- 



XChangeWindowAttributesOXll), 

XConfigureWindowOXl 1), 

XDestroyWindowOXll), 

XMapWindowOXll), 

XRaiseWindowOXll), 

XUnmapWindowOXll) 

Xlib - C Language X Interface 
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NAME 

XDefineCursor, XUndefineCursor ~ define cursors 
SYNTAX 

XDeBneC\irsor(dispky, w, cursor) 
Display * display) 
Window w) 
Cursor cursor-, 

XUndefineCursor(iisplItiy, w) 
Display *display; 
Window w; 

ARGUMENTS 

cursor Specifies the cursor that is to be displayed or None. 

display Specifies the connection to the XwiN server. 

w Specifies the window. 

DESCRIPTION 

If a cursor is set, it will be used when the pointer is in the window. If the cursor 
is None, it is equivalent to XUndefineCursor. 

XDefiyneCuisor can generate BadCursor and BadWindow errors. 

The XUndefineCuursor undoes the effect of a previous XDefineCursor for this 
window. When the pointer is in the window, the parent's cursor will now be 
used. On the root window, the default cursor is restored. 

XUndefineCursor can generate a BadWindow error. 

DIAGNOSTICS 

BadAIloc The server failed to allocate the requested resource or server 

memory. 

BadCursor A value for a Cursor argument does not name a defined Cursor. 

BadWindow A value for a Window argument does not name a defined Win- 
dow. 

SEE ALSO 

XCreateFontCur sor(3Xl 1 ), 

XRecolorCursorOXll) 

Xlib - C Language X Interface 
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NAME 

XDestroyWindow, XDestroySubwindows - destroy windows 

SYNTAX 

XDestroyWmdow(ilispl!fiy, w) 
Display ^disphy; 
Window w; 

XDestroySubwindows (display, w) 
Display "^display; 
Window w, 

ARGUMENTS 

display Specifies the connection to the XwiN server. 

w Specifies the window. 

DESCRIPTION 

The XDestroyWindow function destrojrs the specified window as well as all of its 
subwindows and causes the XwiN server to generate a DestioyNotify event for 
each window. The window should never be referenced again. If the window 
specified by the w argument is mapped, it is unmapped automatically. The ord- 
ering of the DestioyNotify events is such that for any given window being des- 
troyed, DestroyNotify is generated on any inferiors of the window before being 
generated on the window itself. The ordering among siblings and across 
subhierarchies is not otherwise constrained. If the window you specified is a root 
window, no windows are destroyed. Destroying a mapped window will generate 
Expose events on other windows that were obscured by the window b^g des- 
troyed. 

XDestroyWindow can generate a BadWindow error. 

The XDestroySubwindows fimction destroys all inferior windows of the 
specified window, in bottom-to-top stacking order. It causes the XwiN server to 
generate a DestroyNotify event for each window. If any mapped subwindows 
were actually destroyed, XDestroySubwindows causes the XwiN server to gen- 
erate Expose events on the specified window. This is much more efficient than 
deleting many windows one at a time because much of the work need be per- 
formed only once for all of the windows, rather than for each window. The 
subwindows should never be referenced again. 

XDestroySubwindows can generate a BadWindow error. 

DIAGNOSTICS 

BadWindow A value for a Window argument does not name a defined Win- 
dow. 

SEE ALSO 

XChangeWindowAttributes(3Xll), 

XConfigureWindowOXll), 

XCreateWindowOXll), 

XMapWindowOXll), 

XRaiseWindowOXll), 

XUnmapWindowOXll) 

Xlib - C Language X Interface 
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NAME 



XDrawArc, XDrawArcs - draw arcs 



SYNTAX 



XDrawArc(iispky, d, gc, x, y, xmdth, height, anglel, angle!) 
Display * display; 
Drawable 4; 
GC 5c; 
int X, y ; 

unsigned int xmdth, height; 
int anglel, anglel; 

XDrayfArcs(display, d, gc, arcs, narcs) 
Display * display; 
Drawable d; 
GC g^; 



XArc *arcs; 
int narcs; 

ARGUMENTS 

anglel 

anglel 

arcs 
d 

display 

narcs 

width 
height 

X 

y 



Specifies the start of the arc relative to the three-o'clock position 
from the center, in units of degrees * 64. 

Specifies the path and extent of the arc relative to the start of 
the arc, in units of degrees * 64. 

Specifies a pointer to an array of arcs. 

Specifies the drawable. 

Specifies the connection to the XwiN server. 

Specifies the GC. 

Specifies the number of arcs in the array. 

Specify the width and height, which are the major and minor 
axes of the arc. 

Specify the x and y coordinates, which are relative to the origin 
of the drawable and specify the upper-left comer of the boimd- 
ing rectangle. 

DESCRIPTION 

XDrawAic draws a single circular or elliptical arc, and XDrawArcs draws multi- 
ple circular or elliptical arcs. Each arc is specified by a rectangle and two angles. 
The center of the circle or ellipse is the center of the rectangle, and the major and 
minor axes are specified by the width and height. Positive angles indicate cotm- 
terclockwise motion, and negative angles indicate clockwise motion. If the magni- 
tude of angle2 is greater tlum 360 degrees, XDiawAic or XDrawArcs truncates it 
to 360 degrees. 
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For an arc specified as [ x, y, zmM^height^r^lel, angle!], the origin of the 
major and minor axes is at lx+ — - — , y+ — ^ — ], and the infinitely thin path 

describing the entire circle or ellipse intersects the horizontal axis at Ix, y-i- ^S^^ ] 

and lx+ width, y-i- ] and intersects the vertical axis at [x+ ^^^^ , y] and 
tvidth 

lx+ — - — , y-h height]. These coordinates can be fractional and so are not tnm- 

cated to discrete coordinates. The path should be defined by the ideal mathemat- 
ical path. For a wide line with line-width Iw, the bounding outlines for filling are 
given by the two infinitely thin paths consisting of all points whose perpendicular 
distance from the path of the circle/ellipse is equal to lw/2 (which may be a frac- 
tional value). The cap-style and join-style are applied the same as for a line 
corresponding to the tangent of the circle/ellipse at the endpoint. 

For an arc specified as [ x, y, width, height, angle!, angle!], the angles must be 
specified in the effectively skewed coordinate system of the ellipse (for a circle, 
the angles and coordinate systems are identical). The relationship between these 
angles and angles expressed in the normal coordinate system of the screen (as 
measured with a protractor) is as follows: 

tan(normal-angle) * 



skewed-angle = atan 



height 



-^adjust 



The skewed-angle and normal-angle are expressed in radians (rather than in 
degrees scaled by 64) in the range [0, !n] and where atan returns a value in the 

range y] and adjust is: 

0 for normal-angle in the range [0, y ] 

n for normal-angle in the range (y, -—•] 

!k for normal-angle in the range I—, !n] 

For any given arc, XDrawArc and XDrawArcs do not draw a pixel more than 
once. If two arcs join correctly and if the line-width is greater than zero and the 
arcs intersect, XDrawArc and XDrawArcs do not draw a pixel more than once. 
Otherwise, the intersecting pixels of intersecting arcs are drawn multiple times. 
Specifying an arc with one endpoint and a clockwise extent draws the same pix- 
els as specif5dng the other endpoint and an equivalent coimterclockwise extent, 
except as it affects joins. 

If the last point in one arc coincides with the first point in the following arc, the 
two arcs will join correctly. If the first point in the first arc coincides with the last 
point in the last arc, the two arcs will join correctly. By specifying one axis to be 
zero, a horizontal or vertical line can be drawn. Angles are computed based 
solely on the coordinate system and ignore the aspect ratio. 

Both fimctions use these GC components: function, plane-mask, line-width, line- 
style, cap-style, join-style, fill-style, subwindow-mode, clip-x-origin, clip-y-origin. 
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and clip-mask. They also use these GC mode-dependent components: fore- 
ground, backgroimd, tile, stipple, tile-stipple-x-origin, tile-stipple-y-origin, dash- 
offset, and dash-list. 

XDrawAic and XDiawAics can generate BadDrawable, BadGC, and BadMatch 

errors. 

DIAGNOSTICS 

BadDrawable A value for a Drawable argument does not name a defined 
Window or Pixmap. 

BadGC A value for a GContext argument does not name a defined 



GContext. 



BadMatch 
BadMatch 



Some aigument or pair of arguments has the correct type and 
range but fails to match in some other way required by the 
request. 



An InputOnly window is used as a Drawable. 



SEE ALSO 



XDrawLineOXll), 
XDrawPointOXll), 
XDrawRectangle(3Xll) 
Xlib - C Language X Interface 
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NAME 

XDrawlmageString, XDrawImageStringl6 - draw image text 
SYNTAX 

XDrawlmageString (i^ispky, d, gc, x, y, string, length) 
CHsplay ^display; 
Drawable d) 
GCgc; 
int X, y; 
char *string; 
int length; 

XDrawImageStringl6(iispky, d, gc, x, y, string, length) 
Display *display; 
Drawabie d; 
GCgc; 
int X, y; 

XChar2b *$tring; 
int length; 

ARGUMENTS 

d Specifies the drawable. 

display Specifies the connection to the XwiN server. 

gc Specifies the GC. 

length Specifies the number of characters in the string argument. 

string Specifies the character string. 

X 

y Specify the x and y coordinates, which are relative to the origin of 

the specified drawable and define the origin of the first character. 

DESCRIPTION 

The XDiawImageStringl6 function is similar to XDrawlmageString except that 
it uses 2-byte or 16-bit characters. Both functions also use both the foreground 
and background pixels of the GC in the destination. 

The effect is first to fill a destination rectangle with the background pixel defined 
in the GC and then to paint the text with the foregroimd pixel. The upper-left 
corner of the filled rectangle is at: 

[x, y - font-ascent] 
The width is: 

overall-width 
The height is: 

font-ascent + font-descent 

The overall-width, font-ascent, and font-descent are as would be returned by 
XQueiyTextExtents using gc and string. The function and fill-style defined in the 
GC are ignored for these functions. Tlie effective function is GXcopy, and the 
effective fill-style is FillSolid. 
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For fonts defined with 2-byte matrix indexing and used with XDrawlmageString, 
each byte is used as a byteiz with a bytel of zero. 

Both functions use these GC components: plane-mask, foreground, background, 
font, subwindow-mode, clip-x-origin, clip-y-origin, and clip-mask. 

XDrawlmageString and XDrawImageStringl6 can generate BadDiawable, 
BadGC, and BadMatch errors. 

DIAGNOSTICS 

BadDiawable A value for a Drawable argument does not name a defined 
Window or Pixmap. 

BadGC A value for a GContext argument does not name a defined 



GContext. 



BadMatch 
BadMatch 



Some argument or pair of arguments has the correct type and 
range but fails to match in some other way required by the 
request. 



An InputOnly window is used as a Drawable. 



SEE ALSO 



XDrawStringOXll), 

XDrawTextOXll) 

Xlib - C Language X Interface 
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NAME 

XDrawLine, XDrawLines, XDrawSegments - draw lines and polygons 
SYNTAX 

XDraydAne(displajf, d, gc, xl,yl, x2, y2) 
Display ^display; 
Drawable d) 
GCgc; 

int xl,yl,x2,y2; 

XDray/Lines(dispky, d, gc, points, npoints, mode) 
Display ^display; 
Drawable d) 
GC gc; 

XPoint *points; 
int npoints; 
int mode; 

XDrawSegments((/isp%, d, gc, segments, nsegments) 
Dispky *display; 
Drawable d; 
GCgc; 

XSegment *segments; 
int nsegments; 

ARGUMENTS 

d Specifies the drawable. 

display Specifies the connection to the XwiN server. 

gc Specifies the GC. 

mode Specifies the coordinate mode. You can pass CoordModeOiigin 

or CoordModePrevious. 

npoints Specifies the number of points in the array. 

nsegments Specifies the nimiber of segments in the array. 

points Specifies a pointer to an array of points. 

segments Specifies a pointer to an array of segments. 

xl 

yl Specify the points (xl, yl) and (x2, y2) to be connected. 

DESCRIPTION 

The XDrawLine function uses the components of the specified GC to draw a line 
between the specified set of points (xl, yl) and {xl, yl). It does not perform join- 
ing at coincident endpoints. For any given line, XDrawLine does not draw a 
pixel more than once. If lines intersect, the intersecting pixels are drawn multiple 
times. 
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The XDrawLines function uses the components of the specified GC to draw 
npoints-1 lines between each pair of points (point[i], point[i+ll) in the array of 
XPoint structures. It draws the lines in the order listed in the array. The lines 
join correctly at all intermediate points, and if the first and last points coincide, 
the first and last lines also join correctly. For any given line, XDrawLines does 
not draw a pixel more than once. If thin (zero line-width) lines intersect, the 
intersecting pixels are drawn multiple times. If wide lines intersect, the intersect- 
ing pixels are drawn only once, as though the entire Polyline protocol request 
were a single, filled shape. CoordModeOrigin treats all coordinates as relative to 
the origin, and CoordModePrevious treats all coordinates after the first as rela- 
tive to the previous point. 

The XDrawSegments fimction draws multiple, imconnected lines. For each seg- 
ment, XDrawSegments draws a line between (xl, yl) and (x2, y2). It draws the 
lines in the order listed in the array of XSegment structures and does not per- 
form joining at coincident endpoints. For any given line, XDrawSegments does 
not draw a pixel more than once. If lines intersect, the intersectiiig pixels are 
drawn multiple times. 

All three functions use these GC components: function, plane-mask, line-width, 
line-style, cap-style, fill-style, subwindow-mode, clip-x-origin, clip-y-origin, and 
clip-mask. The XDrawLines function also uses the join-style GC component. All 
three functions also use these GC mode-dependent components: foreground, 
background, tile, stipple, tile-stipple-x-origin, tile-stipple-y-origin, dash-offset, and 
dash-list. 

XDrawLine, XDrawLines, and XDrawSegments can generate BadDrawable, 
BadGC, and BadMatch errors. XDrawLines can also generate a BadValue 
error. 



BadDrawable A value for a Drawable argument does not name a defined 
Window or Pixmap. 



DIAGNOSTICS 



BadGC 



A value for a GContext argument does not name a defined 
GContext. 



BadMatch 
BadMatch 



An InputOnly window is used as a Drawable. 



Some argument or pair of argimients has the correct type and 
range but fails to match in some other way required by the 
request. 



BadValue 



Some numeric value falls outside the range of values accepted 
by the request. Unless a specific range is specified for an argu- 
ment, the full range defined by the argtmient's type is accepted. 
Any argument defined as a set of alternatives can generate this 
error. 



SEE ALSO 



XDrawArcOXll), 
XDrawPoint(3Xll), 
XDrawRectangle(3Xll) 
XUb - C Language X Interface 
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NAME 

XDrawPoint, XDrawPoints - draw points 

SYNTAX 

XDrawPoint(iisp%, d, gc, x, y) 
Display *displaif; 
Drawable d; 
GCgc; 
int X, y; 

XDrawPoints (if i^l!ay, d, gc, points, npoints, mode) 
Display * display, 
Drawable d; 

CC gc; 

XPoint *points; 
int npoints; 
int mode; 

ARGUMENTS 

d 

display 

mode 

npoints 
points 

X 

y 

DESCRIPTION 

The XDrawPoInt function uses the foreground pixel and function components of 
the GC to draw a single point into the specified drawable; XDrawPoints draws 
multiple points this way. CoordModeOrigin treats all coordinates as relative to 
the origin, and CooidModePrevious treats all coordinates after the first as rela- 
tive to the previous point. XDrawPoints draws the points in the order listed in 
the array. 

Both functions use these GC components: function, plane-mask, foreground, 
subwindow-mode, clip-x-origin, clip-y-origin, and clipmask. 

XDrawPoint can generate BadDrawable, BadGC, and BadMatch errors. 
XDrawPoint can generate BadDrawable, BadGC, BadMatch, and BadValue 
errors. 

DIAGNOSTICS 

BadDrawable A value for a Drawable argument does not name a defined 
Window or Pixmap. 



Specifies the drawable. 

Specifies the connection to the XwiN server. 

Specifies the GC. 

Specifies the coordinate mode. You can pass CoordModeOrigin 
or CoordModePrevious. 

Specifies the number of points in the array. 

Specifies a pointer to an array of points. 

Specify the x and y coordinates where you want the point 
drawn. 
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BadGC A value for a GContext argument does not name a defined 

GContext. 

BadMatch An InpulOnly window is used as a Drawable. 

BadMatch Some aigument or pair of argtmients has the correct type and 
range but fails to match in some other way required by the 
request. 

BadValue Some numeric value falls outside the range of values accepted 
by the request. Unless a specific range is specified for an argu- 
ment, the full range defined by the argument's type is accepted. 
Any argument defined as a set of alternatives can generate this 
error. 

SEE ALSO 

XDrawArcOXll), 
XDrawLine(3Xll), 
XDrawRectangleOXll) 
Xlib - C Language X Interface 
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NAME 

XDrawRectangle, XDrawRectangles - draw rectangles 
SYNTAX 

XDrawRectangle((lx^iay, d, gc, x, y, width, height) 
Display ^display; 
Drawable d; 
GCgc; 
int X, y; 

unsigned int width, height; 

XDrawRectangles (itsplloy, d, gc, rectangles, nrectangles) 
Display *display; 
Drawable d; 
GCgc; 

XRectangle rectanglesU; 
int nrectangles; 

ARGUMENTS 

d Specifies the drawable. 

display Specifies the connection to the XwiN server. 

gc Specifies the GC. 

nrectangles Specifies the number of rectangles in the array. 
rectangles Specifies a pointer to an array of rectangles. 

uridth 

height Specify the width and height, which specify the dimensions of 

the rectangle. 

X 

y Specify the x and y coordinates, which specify the upper-left 

comer of the rectangle. 

DESCRIPTION 

The XDrawRectangle and XDrawRectangles functions draw the outlines of the 
specified rectangle or rectangles as if a five-point Polyline protocol request were 
specified for each rectangle: 

[x,y] [x+width,y] [x+width,y+heightl [x,y+height] [x,y] 

For the specified rectangle or rectangles, these functions do not draw a pixel more 
than onoe. XDrawRectangles draws the rectangles in the order listed in the 
array. If rectangles intersect, the intersecting pixels are drawn multiple times. 

Both functions use these GC components: function, plane-mask, line-width, line- 
style, join-style, fill-style, subwindow-mode, clip-x-origin, clip-y-origin, and clip- 
mask. They also use these GC mode-dependent components: foreground, back- 
ground, tile, stipple, tile-stipple-x-origin, tile-stipple-y-origin, dash-offset, and 
dash-list. 

XDrawRectangle and XDrawRectangles can generate BadDrawable, BadGC, 
and BadMatch errors. 
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DIAGNOSTICS 

BadDiawable A value for a Drawable argument does not name a defined 
Window or Pixmap. 

BadGC A value for a GContext argument does not name a defined 

GContext. 

BadMatdi An InputOnly window is used as a Drawable. 

BadMatdi Some argument or pair of argtiments has the correct type and 
range but foils to match in some other way required by the 
request. 

SEE ALSO 

XDrawArcOXll), 

XDrawLine(3Xll), 

XDrawPointOXll) 

Xlib - C Language X Interface 
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NAME 

XDrawString, XDrawStringl6 - draw text characters 
SYNTAX 

XDrawString ((^isp%, d, gc, x, y, string, length) 
Display ^display; 
Drawable d; 
GCgc; 
int X, y; 
char *string; 
int length; 

XDrawStringl6(<iisp%, d, gc, x, y, string, length) 
Display ^display; 
Drawable d; 
GCgc; 
int X, y; 

XChar2b *string; 
int length; 



ARGUMENTS 

d Specifies the drawable. 

display Specifies the connection to the XwiN server. 

gc Specifies the GC. 

length Specifies the number of characters in the string argument. 

string Specifies the character string. 

X 

y Specify the x and y coordinates, which are relative to the origin 



of the specified drawable and define the origin of the first char- 
acter. 

DESCRIPTION 

Each character image, as defined by the font in the GC, is treated as an additional 
mask for a fill operation on the drawable. The drawable is modified only where 
the font character has a bit set to 1. For fonts defined with 2-byte matrix index- 
ing and used with XDrawStringl6, each byte is used as a byte2 with a bytel of 
zero. 

Both fimctions use these GC components: function, plane-mask, fill-style, font, 
subwindow-mode, clip-x-origin, clip-y-origin, and clip-mask. They also use these 
GC mode-dependent components: foreground, background, tile, stipple, tile- 
stipple-x-origin, and tile-stipple-y-origin. 

XDrawString and XDrawStruigl6 can generate BadDrawable, BadCC, and 
BadMatch errors. 

DIAGNOSTICS 

BadDrawable A value for a Drawable argument does not name a defined 
Window or Pixmap. 
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BadGC A value for a GContext argument does not name a defined 

GContext. 

BadMatdi An InputOnly window is used as a Drawable. 

BadMatdi Some argument or pair of arguments has the correct type and 
range but fails to match in some other way required by the 
request. 

SEE ALSO 

XDrawImageStringOXll), 

XDrawTextOXll) 

Xlib - C Language X Interface 
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NAME 

XDrawText, XE)rawTextl6 - draw polytext text 
SYNTAX 

XDreiWText(display, d, gc, x, y, Hems, nitems) 
Display *display; 
Drawable d; 
GCgc; 
int X, y; 

XTextltem *items; 
int nitems; 

XDreLWTextl6(display, d, gc, x, y, items, nitems) 
Display * display; 
Drawable d; 
GC gp; 
int X, y; 

XTextIteml6 *items; 
int nitems; 



ARGUMENTS 

d Specifies the drawable. 

display Specifies the connection to the XwiN server. 

gc Specifies the GC. 

items Specifies a pointer to an array of text items. 

nitems Specifies the niimber of text items in the array. 

X 

y Specify the x and y coordinates, which are relative to the origin 
of the specified drawable and define the origin of the first char- 



acter. 
DESCRIPTION 

The XDrawTextl6 function is similar to XDrawText except that it uses 2-byte or 
16-bit characters. Both functions allow complex spacing and font shifts between 
counted strings. 

Each text item is processed in turn. A font member other than None in an item 
causes the font to be stored in the GC and used for subsequent text. A text ele- 
ment delta specifies an additional change in the position along the x axis before 
the string is drawn. The delta is always added to the character origin and is not 
dependent on any characteristics of the font. Each character image, as defined by 
the font in the GC, is treated as an additional mask for a fill operation on the 
drawable. The drawable is modified only where the font character has a bit set 
to 1. If a text item generates a BadFont error, the previous text items may have 
been drawn. 

For fonts defined with linear indexing rather than 2-byte matrix indexing, each 
XChai2b structure is interpreted as a 16-bit number with bytel as the most- 
significant byte. 
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Both functions use these GC components: function, plane-mask, fill-style, font, 
subwindow-mode, clip-x-origin, dip-y-origin, and clip-mask. They also use these 
GC mode-dependent components: foregroimd, background, tile, stipple, tile- 
stipple-x-origin, and tile-stipple-y-origin. 

XDrawText and XDrawTextl6 can generate BadDrawable, BadFont, BadGC, 
and BadMatch errors. 

DIAGNOSTICS 

BadDrawable A value for a Drawable argument does not name a defined 
Window or Pixmap. 



BadFont 



A value for a Font or GContext argument does not name a 
defined Font. 



BadGC 



A value for a GContext argument does not name a defined 
GContext. 



BadMatdi 



An InputOnly window is used as a Drawable. 



SEE ALSO 



XDrawImageStringOXll), 

XDrawStringOXll) 

Xlib - C Language X Interface 
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NAME 

XEmptyRegion, XEqualRegion^ XPointlnRegion, XRectlnRegion - determine if 
regions are empty or equal 

SYNTAX 

Bool XEmptyRegion(r) 
Region r; 

Bool XEqualRegion(r2, r2) 
Region rl,r2; 

Bool XPointInRegion(r, x, y) 
Region r; 
int X, y; 

int XRectInRegion(r, x, y, vndth, he^ht) 
Region r; 
int X, y; 

unsigned int vridth, height; 

ARGUMENTS 

r Specifies the region. 

rl 

rl Specify the two regions. 

vndth 

height Specify the width and height, which define the rectangle. 

X 

y Specify the x and y coordinates, which define the point or the 

coordinates of the upper-left comer of the rectangle. 

DESCRIPTION 

The XEmptyRegion function returns True if the region is empty. 

The XEqualRegion function returns Trae if the two regions have the same offset, 
size, and shape. 

The XPoinllnRegion function returns True if the point (x, y) is contained in the 
region r. 

The XRectlnRegioii function returns Rectanglein if the rectangle is entirely in 
the specified region, RectangleOut if the rectangle is entirely out of the specified 
region, and RectanglePart if the rectangle is partially in the specified region. 

SEE ALSO 

XCreateRegionOXll), 
XIntersectRegionOXll) 
XLib - C Language X Interface 
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NAME 

XFillRectangle, XFillRectangles, XFillPolygon, XFillArc, XFillArcs - fill rectangles, 
polygons, or arcs 

SYNTAX 

XFillRectangle((fisf;ky, d, gc, x, y, vndth, height) 
Display *displey; 
Drawable d) 
GCgc; 
int X, y; 

unsigned int width, height; 

XFillRectangles(i2sp%, d, gc, rectangles, nrectangles) 
Display *display; 
Drawable d; 

GCgc; 

XRectangle *rectangks; 
int nrectangles; 

XFillPolygon ((fisp%, d, gc, points, npoints, shape, mode) 
Display * display; 
Drawable d; 
GCgc; 

XPoint *points; 
int npoints; 
int shape; 
int mode; 

y^iX[krc{display, d, gc, x, y, vMth, height, anglel, angle!) 
Display * display; 
Drawable d; 
GC gc; 
int X, y; 

unsigned int vndth, height; 
int anglel, anglel; 

y^\\\Axcs{display, d, gc, arcs, narcs) 
Display * display; 
Drawable d; 
GCgq; 
XArc *arcs; 
int narcs; 

ARGUMENTS 

anglel Specifies the start of the arc relative to the three-o'clock position 

from the center, in units of degrees * 64. 

angle! Specifies the path and extent of the arc relative to the start of 

the arc, in units of degrees * 64. 

arcs Specifies a pointer to an array of arcs. 
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mode 



npoints 

nrectangles 

points 

rectangles 

shape 



d 



display 



narcs 



Specifies the drawable. 

Specifies the connection to the XwiN server. 

Specifies the GC. 

Specifies the coordinate mode. You can pass CooidModeOrigin 
or CoordModePrevious. 

Specifies the number of arcs in the array. 

Specifies the number of points in the array. 

Specifies the number of rectangles in the array. 

Specifies a pointer to an array of points. 

Specifies a pointer to an array of rectangles. 

Specifies a shape that helps the server to improve performance. 
You can pass Complex, Convex, or Nonconvex. 



width 
height 



Specify the width and height, which are the dimensions of the 
rectangle to be filled or the major and minor axes of the arc. 



X 



y 



Specify the x and y coordinates, which are relative to the origin 
of the drawable and specify the upper-left comer of the rectan- 
gle. 



DESCRIPTION 

The XFillRectangle and XFillRectangles functions fill the specified rectangle or 
rectangles as if a four-point FillPolygon protocol request were specified for each 
rectangle: 

[x,y] [x+width,y] [x+width,y+height] [x,yH-height] 

Each function uses the x and y coordinates, width and height dimensions, and 
GC you specify. 

XFillRectangles fills the rectangles in the order listed in the array. For any given 
rectangle, )CFillRectangle and XFillRectangles do not draw a pixel more than 
once. If rectangles intersect, the intersecting pixels are drawn multiple times. 

Both functions use these GC components: function, plane-mask, fill-style, 
subwindow-mode, clip-x-origin, clip-y-origin, and clip-mask. They also use these 
GC mode-dependent components: foreground, background, tile, stipple, tile- 
stipple-x-origin, and tile-stipple-y-origin. 

XFillRectangle and XFillRecUngles can generate BadDrawable, BadGC, and 
BadMatch errors. 

XFillPolygon fills the region dosed by the specified path. The path is closed 
automatically if the last point in the list does not coincide with the first point. 
XFillPolygon does not draw a pixel of the region more than once. CoordMo- 
deOrigin treats all coordinates as relative to the origin, and CoordModePrevious 
treats all coordinates after the first as relative to the previous point. 
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Depending on the specified shape, the following occurs: 

• If shape is Complex, the path may self-intersect. 

• If shape is Convex, the path is wholly convex. If known by the client, speci- 
fying Convex can improve performance. If you specify Convex for a path 
^t is not conve>^ the graphics results are undefined. 

• If shape is Nonconvex, the path does not self-intersect, but the shape is not 
wholly convex. If known the client, specifying Nonconvex instead of 
Complex may improve performance. If you specify Nonconvex for a self- 
intersecting path, ihe graphics results are undefined. 

The fill-rule of the GC controls the filling behavior of self-intersecting polygons. 

This function uses these GC components: function, plane-mask, fill-style, fill-rule, 
subwindow-mode, clip-x-origin, clip-y-origin, and clip-mask. It also uses these 
GC mode-dependent components: foreground, background, tile, stipple, tile- 
stipple-x-origin, and tile-stipple-y-origin. 

XFillPolygon can generate BadDrawable, BadGC, BadMatch, and BadValue 
errors. 

For each arc, XFillArc or XFillAics fills the region closed by the infinitely thin 
path described by the specified arc and, depending on the arc-mode specified in 
the GC, one or two line segments. For ArcChord, the single line segment joining 
the endpoints of the arc is used. For ArcPieSIice, the two line segments joining 
the endpoints of the arc with the center point are used. XFillArcs fills the arcs in 
the order listed in the array. For any given arc, XFillArc and XFillArcs do not 
draw a pixel more than once. If regions intersect, the intersecting pixels are 
drawn multiple times. 

Both functions use these GC components: function, plane-mask, fill-style, arc- 
mode, subwindow-mode, clip-x-origin, clip-y-origin, and clip-mask. Tjfiey also 
use these GC mode-dependent components: foreground, background, tile, stipple, 
tile-stipple-x-origin, and tile-stipple-y-origin. 

XFillArc and XFillArcs can generate BadDrawable, BadGC, and BadMatch 

errors. 

DIAGNOSTICS 

BadDrawable 

BadGC 

BadMatch 
BadMatch 



BadValue 



A value for a Drawable argument does not name a defined 
Window or Pixmap. 

A value for a GContext argument does not name a defined 
GContext. 

An InputOnly window is used as a Drawable. 

Some argument or pair of arguments has the correct type and 
range but foils to match in some other way required by the 
request. 

Some numeric value falls outside the range of values accepted 
by the request. Unless a specific range is specified for an argu- 
ment, the full range defined by the argument's type is accepted. 
Any argument defined as a set of alternatives can generate this 
error. 
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SEE ALSO 

XDrawArcOXll), 
XDrawRectangle(3Xll) 
Xlib - C Language X Interface 
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NAME 

XFlush, XSync, XEventsQueued, XPending - handle output buffer or event queue 

SYNTAX 

XFhish(display) 

Display * display) 

XSync(display, discard) 
Display ^display; 
Bool discard; 

int XEventsQueued (iispliiy, mode) 
Display *display; 
int mode; 

int XPending(ifs^%) 
Display ^display; 

ARGUMENTS 

discard Specifies a Boolean value that indicates whether XSync discards 

all events on the event queue. 

display Specifies the connection to the XwiN server. 

mode Specifies the mode. You can pass QueuedAlready, QueuedAf- 

lerFlush, or QueuedAfterReading. 

DESCRIPTION 

The XFlush function flushes the output buffer. Most client applications need not 
use this function because the output buffer is automatically flushed as needed by 
calls to XPending, XNextEvent, and XWindowEvent. Events generated by the 
server may be enqueued into the library's event queue. 

The XSync function flushes the output buffer and then waits until all requests 
have been received and processed by the XwiN server. Any errors generated 
must be handled by the error handler. For each error event received by Xlib, 
XSync calls the client application's error handling routine (see section 8.12.2, 
Xlib — C Language X Interface), Any events generated by the server are enqueued 
into the library's event queue. 

Finally, if you passed False, XSync does not discard the events in the queue. If 
you passed True, XSync discards all events in the queue, including those events 
that were on the queue before XSync was called. Client applications seldom 
need to call XS3mc. 

If mode is QueuedAlready, XEventsQueued returns the number of events 
already in the event queue (and never performs a system call). If mode is 
QueuedAfterFlush, XEventsQueued returns the number of events already in the 
queue if the nimiber is nonzero. If there are no events in the queue, 
XEventsQueued flushes the output buffer, attempts to read more events out of 
the application's connection, and returns the nimiber read. If mode is 
QueuedAfterReading, XEventsQueued returns the number of events already in 
the queue if the number is nonzero. If there are no events in the queue, 
XEventsQueued attempts to read more events out of the application's connection 
without flushing the output buffer and returns the mmiber read. 
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XEventsQueued always rettims immediately without I/O if there are events 
already in the queue. XEventsQueued with mode QueuedAfterFlush is identical 
in behavior to XPending. XEventsQueued with mode QueuedAlready is identi- 
cal to the XQLength function. 

The XPending function returns the number of events that have been received 
from the XwiN server but have not been removed from the event queue. XPend- 
ing is identical to XEventsQueued with the mode QueuedAfterFlush specified. 

SEE ALSO 

XlfEventOXll), 

XNextEventOXll), 

XPutBackEventOXll) 

Xlib - C Language X Interface 
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NAME 

XFree, XNoOp - free dient data 

SYNTAX 

XFreeidata) 
char "^data; 

Xt^oOp(display) 
Display *display; 

ARGUMENTS 

display Specifies the connection to the XwiN server. 

data Specifies a pointer to the data that is to be freed. 

DESCRIPTION 

The XFree function is a general-ptirpose Xlib routine that frees the specified data. 
You must use it to free any objects that were allocated by Xlib. 

The XNoOp function sends a NoOpeiation protocol request to the XwiN server, 
thereby exercising the connection. 

SEE ALSO 

Xlib - C Language X Interface 
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NAME 

XGetDefault, XResourceManagerString - get X program defaults 
SYNTAX 

char *XGeiDefeLu\i(display, program, option) 
Display * display; 
char ^program', 
char ^option) 

char '^XResourceManagerString (iisp%) 
Display ^display; 

ARGUMENTS 

display Specifies the connection to the XwiN server. 

option Specifies the option name. 

program Specifies the program name for the Xlib defaults (usually 

argv[0] of the main program). 

DESCRIPTION 

The XGetDefault function returns the value NULL if the option name specified 
in this argument does not exist for the program. The strings returned by XGet- 
Default are owned by Xlib and should not be modified or freed by the dient. 

The XResourceManagerString returns the RESOURCE MANAGER property 
from the server's root window of screen zero, which was returned when the con- 
nection was opened using XOpenDisplay. 

SEE ALSO 

XrmGetSearchList(3Xll) 
Xlib - C Language X Interface 
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NAME 

XrmGetResource, XrmQGetResource, XrmQGetSearchList, XrmQGetSear- 
chResotirce - retrieve database resources and search lists 

SYNTAX 

Bool XTmGetReso\irce(database, sirjume, strjUass, strjypejretum, value jetum) 
XrmDatabase database; ~ 
char *slr_mifie; 
char *strjHass; 
char **strj}fpe_retum; 
Xrm Value *value_retum; 

Bool XrmQGetResource(ia(alxase, quarkjtame, ifuarkj:1ass, .br 
qmrkjypejrelum, vdluejretum) 
XrmDatabase database; 
XrmNameList quark jiame; 
XrmQassList quark_c1ass; 
XrmRepresentation *(fuarkjypejetum; 
Xrm Value *vailuejreium; 

typedef XrmHashTable ^XrmSearchList; 

Bool XrmQGetSearchListC^ol^ase, names, classes, listjetum, Ustjength) 
XrmDatabase database; 
XrmNameList names; 
XrmQassList classes; 
XrmSearchList listjetum; 
int listjength; 

Bool XrmQGetSearchResource(/tst, name, class, typejeturn, valuejeturn) 
XrmSearchList list; 
XrmName name; 
XrmQass class; 

XrmRepresentation *typejeium; 
Xrm Value "^valuejetum; 

ARGUMENTS 



class 


Specifies the resource class. 


classes 


Specifies a list of resource classes. 


dafabasf 


Specifies the database that is to be used. 


list 


Specifies the search list returned by XimQGetSearchList. 


listjength 


Specifies the number of entries (not the byte size) allocated for 




list_retum. 


listjetum 


Returns a search list for further use. 


name 


Specifies the resource name. 


names 


Specifies a list of resource names. 
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cjmrkjilass Specifies the fully qualified class of the value being retrieved (as 
a quark). 

quark jiame Specifies the fully qualified name of the value being retrieved 
(as a quark). 

quark Jypejretum 

Returns a pointer to the representation type of the destination 
(as a quark). 

strjilass Specifies the fully qualified dass of the value being retrieved (as 

a string). 

strjtame Specifies the fully qualified name of the value being retrieved 

(as a string). 

strjype_retum Returns a pointer to the representation type of the destination 
(as a string). 

iypejetum Returns data representation type, 
vduejetum Returns the value in the database. 
DESCRIPTION 

The XrmGetResource and XrmQGetResource functions retrieve a resource from 
the specified database. Both take a fully qualified name/class pair, a destination 
resource representation, and the address of a value (size/address pair). The value 
and returned type point into database memory; therefore, you must not modify 
the data. 

The database only frees or overwrites entries on XrmPutResource, 
XrmQPutResource, or XimMeigeDatabases. A client that is not storing new 
values into the database or is not merging the database should be safe using the 
address passed back at any time until it exits. If a resource was found, both 
XrmGetResource and XimQGetResource return True; otherwise, they return 
False. 

The XrmQGetSearchList function takes a list of names and classes and returns a 
list of database levels where a match might occur. The returned list is in best-to- 
worst order and uses the same algorithm as XrmGetResource for determining 
precedence. XrmQGetSearchList returns True if list_return was large enough 
for the search list, otherwise, it returns False. ~ 

The size of the search list that the caller must allocate is dependent upon the 
number of levels and wildcards in the resource specifiers that are stored in the 
database. The worst case length is 3", where n is the number of name or class 
components in names or classes. 

When using XrmQGetSearchList followed by multiple probes for resources with 
a common name and class prefix, only the common prdEbc should be specified in 
the name and class list to XimQGetSearchList. 

The XimQGetSearchResource function searches the specified database levels for 
the resource that is fully identified by the specified name and class. The search 
stops with the first match. XrmQGetSearchResouice returns True if the 
resource was found; otherwise, it returns False. 
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A call to XimQGetSeardiList with a name and class list containing all but the 
last component of a resource name followed by a call to 

XrmQGetSearchResouice with the last component name and class returns the 
same database entry as XrmGetResource and XnnQGetResource with the fully 
qualified name and dass. 

SEE ALSO 

XrmInitialize(3Xll), 
XrmMergeDatabasesOXll), 
XrmPutResourceOXll), 
XrmUniqueQuarkOXll) 
XIW - C Language X Interface 
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NAME 

XGetVisuallnfb, XMatchVisuallnfo^ XVisuallDFromVisual - obtain visual informa- 
tion 

SYNTAX 

XVisuallnfo "^XGetVistiallnfoCiisp^, vinfojmsk, vinfojemplate, nitemsjretum) 
Display * display; 
long vinfojnask; 
XVisuallnfo "^vinfojemplate; 
int ^nitemsj'etum; 

Status XMatchVisualInfo(ii5pl!ay, screen, depth, class, vinfojeturn) 
Display ^display; 
int screen; 
int depth; 
int class; 

XVisuallnfo *vinfojetum; 

VisuallD XVisuallDFromVisuaKvzsua/) 
Visual *xnsual; 

ARGUMENTS 



class 


Specifies the class of the screen. 


depth 


Specifies the depth of the screen. 


display 


Specifies the connection to the XwiN server. 


nitemsjretum 


Returns the number of matching visual structures. 


screen 


Specifies the screen. 


visual 


Specifies the visual type. 


vinfojnask 


Specifies the visual mask value. 


vinfojrelum 


Returns the matched visual information. 


vinfojemplate 


Specifies the visual attributes that are to be used in matching 


the visual structures. 



DESCRIPTION 

The XGetVisuallnfo function returns a list of visual structures that match the 
attributes specified by vinfo_template. If no visual structures match the template 
using the specified vinfo_mask, XGetVisuallnfo returns a NULL. To free the 
data returned by this function, use XFree. 

The XMatchVisuallnfo function returns the visual information for a visual that 
matches the specified depth and class for a screen. Because multiple visuals that 
match the specified depth and class can exist, the exact visual chosen is 
undefined. If a visual is foimd, XMatchVisuallnfo returns nonzero and the 
information on the visual to vinfo_retum. Otherwise, when a visual is not found, 
XMatchVisuallnfo returns zero. 

The XVisuallDFromVisual function returns the visual ID for the specified visual 
type. 
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SEE ALSO 

Xlib - C Language X Interface 
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NAME 

XGetWindowAttributes, XGetGeometry - get current window attribute or 
geometry 

SYNTAX 

Status XGetWindowAttributes (ifsp%, w, window jiitributesjeiurn) 
Display * display, 
Window w; 

XWindowAttributes *windowjittributesjeturn; 

Status XGetGeometryCiispky, d, rootjetum, xjeturn, yjetum, width jetum, 
height ^return, border jvidthjretum, depthjreturn) 
Display ^display; 
Drawable d; 
Window *root_return; 
int *xjeturn, *y_return; 
unsigned int *tvidth_retum, *heightj^etum; 
unsigned int *borderjmdihj'etum; 
unsigned int *depthjelum) 

ARGUMENTS 

border jvidthjeturn 

Returns the border width in pixels. 

d Specifies the drawable, which can be a window or a pixmap. 

depth jetum Returns the depth of the drawable (bits per pixel for the object). 

display Specifies the connection to the XwiN server. 

rootjetum Returns the root window. 

w Specifies the window whose current attributes you want to 
obtain. 

widthjetum 

height jetum Return the drawable's dimensions (width and height). 

window jdtributes jetum 

Returns the specified window's attributes in the XWindowAttri- 
butes structure. 

xjeturn 

y'jetum Return the x and y coordinates that define the location of the 

drawable. For a window, these coordinates specify the upper- 
left outer comer relative to its parent's origin. For pixmaps, 
these coordinates are alwa)^ zero. 

DESCRIPTION 

The XGetWindowAttributes function returns the current attributes for the 
specified window to an XWindowAttributes structure. 

XGetWindowAttributes can generate BadDrawable and BadWindow errors. 

The XGetGeometiy function returns the root window and the current geometry 
of the drawable. The geometry of the drawable includes the x and y coordinates, 
width and height, border width, and depth. These are described in the argument 
list. It is legal to pass to this function a window whose class is InputOnly. 
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DIAGNOSTICS 

BadDiawable A value for a Drawable argument does not name a defined 
Window or Bxmap. 

BadWindow A value for a Window ailment does not name a defined Win- 
dow. 

SEE ALSO 

XQueryPointerOXll), 

XQueryTree(3Xll) 

Xlib - C Language X Interface 
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NAME 

XGetWindowProperty, XListProperties, XChangeProperty, XRotateWindowPro- 
perties, XDeletePJt)perty - obtain and change window properties 

SYNTAX 

int XGetWindowProperty(<fispIay, w, property, hng_pffset, longjength, delete, 

teqjype, actual Jypejetum, actmljormatjetum, nttemsjreturn, 
hyiesjifierjetum, propjetum) 

Display ^display) 

Window w; 

Atom property; 

long long offset, long length) 

Bool delOe) 

Atom reqjype; 

Atom "^actual Jypejetum; 

int ^actual Jormatjetum; 

unsigned long *mtemsj'etum; 

unsigned long *bytes_afterjetum; 

unsigned char *^propyeturn; 

Atom *XListPropertiesWtspky, w, numjnopjretum) 
Display * display; 
Window w; 
int *numjnropjetum; 

XChangePropertyCiispIfly, w, property, type, format, mode, data, nelements) 
Display ^display; 
Window w; 
Atom property, type; 
int format; 
int mode; 

unsigned char *data; 
int nelements; 

XRotateWindowProperties (<^isp%, w, properties, numjprop, npositions) 
Display *display; 
Window w; 
Atom properties [] ; 
int numjtrop; 
int npositions; 

XDeleteProperiy(display, w, property) 
Display '^display; 
Window w; 
Atom property; 

ARGUMENTS 

actual Jormatjetum 

Returns the actual format of the property. 
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actmljypejeturn 

bytes jifterjetum 

dfftu 
delete 



display 
format 



longjength 

longj>ffset 

mode 

nelements 
nitemsjetum 

numjprop 

numjfropjretum 

npositions 

ffrop_retum 

property 

properties 

reqjype 

w 



Returns the atom identifier that defines the actual type of the 
property. 

Returns the number of bytes remaining to be read in the pro- 
perty if a partial read was performed. 

Specifies the property data. 

Specifies a Boolean value that determines whether the property 
is deleted. 

Specifies the connection to the XwiN server. 

Specifies whether the data should be viewed as a list of 8-bit, 
16-bit, or 32-bit quantities. Possible values are 8, 16, and 32. 
This information allows the XwiN server to correctly perform 
bj^te-swap operations as necessary. If the format is 16-bit or 
32-bit, you must explicitly cast your data pointer to a (char *) in 
the call to XChangeProperty. 

Specifies the length in 32-bit multiples of the data to be 
retrieved. 

Specifies the offset in the specified property (in 32-bit quantities) 
where the data is to be retrieved. 

Specifies the mode of the operation. You can pass 
PropModeReplace, PropModePrepend, or PropModeAppend. 

Specifies the number of elements of the specified data format. 

Returns the actual number of 8-bit, 16-bit, or 32-bit items stored 
in the prop_retum data. 

Specifies the length of the properties array. 

Returns the length of the properties array. 

Specifies the rotation amount. 

Returns a pointer to the data in the specified format. 

Specifies the property name. 

Specifies the array of properties that are to be rotated. 

Specifies the atom identifier associated with the property type 
or AnyPropertyType. 

Specifies the type of the property. The XwiN server does not 
interpret the type but simply passes it back to an application 
that later calls XGetWindowProperty. 

Specifies the window whose property you want to obtain, 
change, rotate or delete. 
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DESCRIPTION 

The XGetWindowProperty function returns the actual type of the property; the 
actual format of the property; the number of 8-bit, 16-bit, or 32-bit items 
transferred; the number of bytes remaining to be read in the property; and a 
pointer to the data actually returned. XGetWindowProperty sets the return 
arguments as follows: 

• If the specified property does not exist for the specified window, XGetWin- 
dowProperty returns None to actual_t3^_retum and the value zero to 
actual_format_retum and bytes_after_retum. The nitems_retum argument 
is empty. In this case, the delete argument is ignored. 

• If the specified property exists but its type does not match the specified 
type, XGetWindowProperty returns the actual property type to 
actual_type_retum, the actual property format (never zero) to 
actuarformat^retum, and the property length in bytes (even if the 
actual_format_retum is 16 or 32) to bytes_after_retum. It also ignores the 
delete argument. The nitems_retum argument is empty. 

• If the specified property exists and either you assign AnyPropertyType to 
the req^type argument or the specified type matches the actual property 
type, XGetWindowProperty returns the actual property type to 
actual_t)^_return and the actual property format (never zero) to 
actual__format_retum. It also returns a value to bytes_after_retum and 
nitems_retum, by defining the following values: 

N = actual length of the stored property in bytes 

(even if the format is 16 or 32) 
1 = 4* long_offset 
T = N-I 

L = MINIMUMCr, 4 * long length) 
A = N-(I + L) 

The returned value starts at byte index I in the property (indexing from 
zero), and its length in b5^es is L. If the value for long_offset causes L to be 
negative, a BadValue error results. The value of bytes_after_retum is A, 
giving the nimiber of trailing imread bytes in the stored property. 

XGetWindowProperty always allocates one extra byte in prop_retum (even if the 
property is zero length) and sets it to ASCII null so that simple properties con- 
sisting of characters do not have to be copied into yet another string before use. 
If delete is True and bytes_after_ieturn is zero, XGetWindowProperty deletes 
the property from the window and generates a PropertyNotify event on the win- 
dow. 

The function returns Success if it executes successfully. To free the resulting 
data, use XFiee. 

XGetWindowProperty can generate BadAtom, BadValue, and BadWindow 
errors. 
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The XListProperties function returns a pointer to an array of atom properties 
that are defined for the specified window or returns NULL if no properties were 
found. To free the memory allocated by this function, use XFree. 

XListProperties can generate a BadWindow error. 

The XQiangeProperty function alters the property for the specified window and 
causes the XwiN server to generate a PiopertyNotify event on that window. 
XChangeProperty performs the following: 

• If mode is PropModeReplace, XChangeProperty discards the previous pro- 
perty value and stores the new data. 

• If mode is PropModePrepend or PiopModeAppend, XQiangeProperty 

inserts the specified data before the beginning of the existing data or onto 
the end of the existing data, respectively. The type and format must match 
the existing property value, or a BadMatdi error results. If the property is 
imdefined, it is treated as defined with the correct type and format with 
zero-length data. 

The lifetime of a property is not tied to the storing client. Properties remain until 
explicitly deleted, until the window is destroyed, or imtil the server resets. For a 
discussion of what happens when the connection to the XwiN server is closed, see 
section 2.5, Xlib — C Langw^e X Interface. The maximum size of a property is 
server dependent and can vary dynamically depending on the amount of memory 
the server has available. (If there is insufficient space, a BadAlloc error results.) 

XChangeProperty can generate BadAlloc, BadAtom, BadMatch, BadValue, and 
BadWindow errors. 

The XRotaleWindowProperties function allows you to rotate properties on a 
window and causes the XwiN server to generate PropertyNotify events. If the 
property names in the properties array are viewed as being numbered starting 
from zero and if there are numprop property names in the list, then the value 
associated with property name 1 becomes the value associated with property 
name (I + npositions) mod N for all I from zero to N - 1. The effect is to rotate 
the states by npositions places around the virtual ring of property names (right 
for positive npositions, left for negative npositions). If npositions mod N is 
nonzero, the XwiN server generates a PropertyNotify event for each property in 
the order that they are listed in the array. If an atom occurs more than once in 
the list or no property with that name is defined for the window, a BadMatch 
error results. If a BadAtom or BadMatch error results, no properties are 
changed. 

XRotateWindowProperties can generate BadAtom, BadMatch, and BadWindow 

errors. 

The XDeleteProperty function deletes the specified property only if the property 
was defined on the specified window and causes the XwiN server to generate a 
PropertyNotify event on the window unless the property does not exist. 

XDeleteProperty can generate BadAtom and BadWindow errors. 
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DIAGNOSTICS 

BadAlloc 

BadAtom 
BadValue 



BadWindow 



The server failed to allocate the requested resource or server 
memory. 

A value for an Atom argument does not name a defined Atom. 

Some nimieric value falls outside the range of values accepted 
by the request. Unless a specific range is specified for an argu- 
ment, the full range defined by the argument's type is accepted. 
Any argument defined as a set of alternatives can generate this 
error. 

A value for a Window argument does not name a defined Win- 
dow. 



SEE ALSO 

XInternAtomOXll) 

Xlib - C Language X Interface 
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NAME 

XGrabButton, XUngrabButton - grab pointer buttons 
SYNTAX 

XGrabButton (iisp%, button, modifiers, grabjanndow, ofumerjvents, event jrtask, 
pointerjnode, keyboard jnode, confine Jo, cursor) 
Display *display; 
unsigned int button; 
unsigned int modifiers; 
Window grabjunndow; 
Bool owner jvisnts; 
unsigned int event jnask; 
int pointerjnode, keyboard jnode; 
Window confine Jo; 
Cursor cursor; 

XUngrabButton(iisp2ay, button, modifiers, grabjunndow) 
Display * display; 
unsigned int button; 
unsigned int modifiers; 
Window grabjoindow; 

ARGUMENTS 

button 

confinejo 
cursor 
display 
eventjnask 



grabjunndow 
keyboardjnode 

modifiers 

ovmer events 



pointerjnode 
DESCRIPTION 

The XGrabButton function establishes a passive grab. In the future, the pointer 
is actively grabbed (as for XGrabPointer), the last-pointer-grab time is set to the 
tin\e at which the button was pressed (as transmitted in the ButtonPress event), 
and the ButtonPress event is reported if all of the following conditions are true: 



Specifies the pointer button that is to be grabbed or released or 
AnyButton. 

Specifies the window to confine the pointer in or None. 

Specifies the cursor that is to be displayed or None. 

Specifies the connection to the XwiN server. 

Specifies which pointer events are reported to the client. The 
mask is the bitwise inclusive OR of the valid pointer event mask 
bits. 

Specifies the grab window. 

Specifies further processing of keyboard events. You can pass 
GrabModeSync or GrabModeAsync. 

Specifies the set of keymasks or AnyModifier. The mask is the 
bitwise inclusive OR of the valid keymask bits. 

Specifies a Boolean value that indicates whether the pointer 
events are to be reported as usual or reported with respect to 
the grab window if selected by the event mask. 

Specifies further processing of pointer events. You can pass 
GrabModeSync or GrabModeAsync. 
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• The pointer is not grabbed, and the specified button is logically pressed 
when the specified modifier keys are logically down, and no other buttons 
or modifier keys are logically down. 

• The grab_window contains the pointer. 

• The confine_to window (if any) is viewable. 

• A passive grab on the same button/key combination does not exist on any 
ancestor of grab_window. 

The interpretation of the remaining arguments is as for XGrabPointer. The 
active grab is terminated automatically when the logical state of the pointer has 
all buttons released (independent of the state of the logical modifier keys). 

Note that the logical state of a device (as seen by client applications) may lag the 
physical state if device event processing is frozen. 

This request overrides all previous grabs by the same client on the same 
button/key combinations on the same window. A modifiers of AnyModifier is 
equivalent to issuing the grab request for all possible modifier combinations 
(including the combination of no modifiers). It is not required that all modifiers 
specified have currently assigned KeyCodes. A button of AnyButton is 
equivalent to issuing the request for all possible buttons. Otherwise, it is not 
required that the specified button currently be assigned to a physical button. 

If some other client has already issued a XGrabButton with the same button/key 
combination on the same window, a BadAccess error results. When using 
AnyModifier or AnyButton, the request fails completely, and a BadAccess error 
results (no grabs are established) if there is a conflicting grab for any combina- 
tion. XGrabButton has no effect on an active grab. 

XGrabButton can generate BadCursor, BadValue, and BadWindow errors. 

The XUngrabButton function releases the passive button/key combination on the 
specified window if it was grabbed by this dient. A modifiers of AnyModifier is 
equivalent to issuing the ungrab request for all possible modifier combinations, 
including the combination of no modifiers. A button of AnyButton is equivalent 
to issuing the request for all possible buttons. XUngrabButton has no effect on 
an active grab. 

XUngrabButton can generate BadValue and BadWindow errors. 
DIAGNOSTICS 

BadCursor A value for a Cursor argument does not name a defined Cursor. 

BadValue Some numeric value falls outside the range of values accepted 

by the request. Unless a specific range is specified for an argu- 
ment, the full range defined by the argimient's type is accepted. 
Any argument defined as a set of alternatives can generate this 
error. 

BadWindow A value for a Window argument does not name a defined Win- 
dow. 
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SEE ALSO 

XAllowEvents(3Xll), 
XGrabPointerOXll), 
XGrabKeyOXll), 
XGrabKeyboardOXll), 
XlUf - C Language X Interface 
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NAME 

XGrabKey, XUngrabKey - grab keyboard keys 
SYNTAX 

XGrabKey (display, keycode, modifiers, grdbjvindow, ovmerjvents, pointer jnode, 
keyboardjnode) 
Display * display; 
int keycode) 

unsigned int modifiers) 
Window grabjanndow) 
Bool owner jvents) 
int pointer jnode, keyhoardjnode) 

XUngrabKey(iispky, keycode, modifiers, grabjoindow) 
Display * display) 
int keycode) 

unsigned int modifiers) 
Window grabjmndow) 

ARGUMENTS 

display Specifies the connection to the XwiN server. 

grabjmndow Specifies the grab window. 

keyhoardjnode Specifies further processing of keyboard events. You can pass 
GrabModeS)^c or GrabModeAsync. 

keycode Specifies the Ke3<Iode or AnyKey. 

modifiers Specifies the set of keymasks or AnyModifier. The mask is the 

bitwise inclusive OR of the valid keymask bits. 

owner jvents Specifies a Boolean value that indicates whether the pointer 
events are to be reported as usual or reported with respect to 
the grab window if selected by the event mask. 

pointer jnode Specifies further processing of pointer events. You can pass 
' GrabModeSync or GiabModeAsync. 

DESCRIPTION 

The XGiabKey function establishes a passive grab on the keyboard. In the 
future, the keyboard is actively grabbed (as for XGrabKeyboard), the last- 
keyboard-grab time is set to the time at which the key was pressed (as transmit- 
ted in the KeyPress event), and the KeyPress event is reported if all of the fol- 
lowing conditions are true: 

• The keyboard is not grabbed and the specified key (which can itself be a 
modifier key) is logically pressed when the specified modifier keys are logi- 
cally down, and no other modifier keys are logically down. 

• Either the grab_window is an ancestor of (or is) the focus window, or the 
grab^window is a descendant of the focus window and contains the pointer. 

• A passive grab on the same key combination does not exist on any ancestor 
of grab__window. 
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The interpretation of the remaining arguments is as for XGrabKeyboard. The 
active grab is terminated automaticadly when the logical state of the keyboard has 
the specified key released (independent of the logical state of the modifier keys). 

Note that the logical state of a device (as seen by client applications) may lag the 
physical state if device event processing is frozen. 

A modifiers argument of AnyModifier is equivalent to issuing the request for all 
possible modifier combinations (including the combination of no modifiers). It is 
not required that all modifiers specified have currently assigned KeyCodes. A 
keycode argument of AnyKey is equivalent to issuing the request for all possible 
KeyCodes. Otherwise, the specified keycode must be in the range specified by 
min_keycode and max__keycode in the connection setup, or a BadValue error 
results. 

If some other client has issued a XGrabKey with the same key combination on 
the same window, a BadAccess error results. When using AnyModifier or Any- 
Key, the request fails completely, and a BadAccess error results (no grabs are 
established) if there is a conflicting grab for any combination. 

XGrabKey can generate BadAccess, BadValue, and BadWindow errors. 

The XUngrabKey function releases the key combination on the specified window 
if it was grabbed by this client. It has no effect on an active grab. A modifiers of 
AnyModifier is equivalent to issuing the request for all possible modifier combi- 
nations (including the combination of no modifiers). A keycode argument of 
AnyKey is equivalent to issuing the request for all possible key codes. 

XUngrabKey can generate BadValue and BadWindow error. 

DIAGNOSTICS 

BadAccess A client attempted to grab a key /button combination already 
grabbed by another client. 

BadValue Some nimieric value falls outside the range of values accepted 

by the request. Unless a specific range is specified for an argu- 
ment, the full range defined by the argiunent's type is accepted. 
Any argument defined as a set of alternatives can generate this 
error. 

BadWindow A value for a Window argument does not name a defined Win- 
dow. 

SEE ALSO 

XAUowAccessOXll), 

XGrabButtonOXll), 

XGrabKeyboardOXll), 

XGrabPointer(3Xll) 

Xlib - C Language X Interface 
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NAME 

XGrabKeyboard, XUngrabKeyboard - grab the keyboard 
SYNTAX 

int XGrabKeyboard (ii'^2ay, grabjmndow, oumerjvents, pointer jnode, 
keyboard jnode, time) 
Display ^display; 
Window grabjmndow; 
Bool owner jvents) 
int pointer jnode, keyboard jnode; 
Time timej 

XUngrabKeyboard (ii^biy, time) 
Display ^display; 
Time time; 

ARGUMENTS 

display 

grabjmndow 
keyboardjnode 

ovmer events 



pointer jnode 
time 
DESCRIPTION 

The XGrabKeyboard function actively grabs control of the keyboard and gen- 
erates Focusin and FocusOut events. Further key events are reported only to 
the grabbing client. XGrabKeyboard overrides any active keyboard grab by this 
client. If owner_events is False, all generated key events are reported with 
respect to grab_window. If owner_events is True and if a generated key event 
would normally be reported to this client, it is reported normally; otherwise, the 
event is reported with respect to the grab_window. Both KeyPress and 
KeyRelease events are always reported, independent of any event selection made 
by the client. 

If the keyboard_mode argument is GrabModeAsync, keyboard event processing 
continues as usual. If the keyboard is currently frozen by this client, then process- 
ing of keyboard events is resumed. If the keyboard_mode argument is 
GrabModeSync, the state of the keyboard (as seen by client applications) appears 
to freeze, and the XwiN server generates no further keyboard events untU the 
grabbing client issues a releasing XAllowEvents call or until the keyboard grab is 
released. Actual keyboard changes are not lost while the keyboard is frozen; they 
are simply queued in the server for later processing. 



Specifies the connection to the XwiN server. 
Specifies the grab window. 

Specifies further processing of keyboard events. You can pass 
GrabModeSync or GrabModeAsync. 

Specifies a Boolean value that indicates whether the pointer 
events are to be reported as usual or reported with respect to 
the grab window if selected by the event mask. 

Specifies further processing of pointer events. You can pass 
GrabModeSync or GrabModeAsync. 

Specifies the time. You can pass either a timestamp or Current- 
Time. 
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If pomter_mode is GrabModeAsync, pointer event processing is unaffected by 
activation~bf the grab. If pointer_mode is GmbModeSync, the state of the pointer 
(as seen by client applications) appears to freeze, and the XwiN server generates 
no further pointer events until the grabbing client issues a releasing XAl- 
lowEvents call or until the keyboard grab is released. Actual pointer changes are 
not lost while the pointer is frozen; they are simply queued in the server for later 
processing. 

If the keyboard is actively grabbed by some other client, XGiabKeyboard fails 
and returns AlreadyGiabbed. If grab_window is not viewable, it fsdls and 
returns GiabNotViewable. If the keyboard is frozen by an active grab of 
another client, it fails and returns GxabFrozen. If the specified time is earlier 
than the last-keyboard-grab time or later than the current XwiN server time, it 
fails and returns GiablnvalidTime. Otherwise, the last-keyboard-grab time is set 
to the specified time (CuirentTime is replaced by the current XwiN server time). 

XGrabKeyboaid can generate BadValue and BadWindow errors. 

The XUngrabKeyboard function releases the keyboard and any queued events if 
this client has it actively grabbed from either XGrabKeyboard or XGrabKey. 
XUngrabKeyboard does not release the keyboard and any queued events if the 
specified time is earlier than the last-keyboard-grab time or is later than the 
current XwiN server time. It also generates FocusIn and FocusOut events. The 
XwiN server automatically performs an UngrabKeyboard request if the event 
window for an active keyboard grab becomes not viewable. 

DIAGNOSTICS 

BadValue Some numeric value falls outside the range of values accepted 
by the request. Unless a specific range is specified for an argu- 
ment, the full range defined by the argument's type is accepted. 
Any argument defined as a set of alternatives can generate this 
error. 

BadWindow A value for a Window aigument does not name a defined Win- 
dow. 

SEE ALSO 

XAUowEventsOXll), 

XGrabButtonOXll), 

XGiabKeyOXll), 

XGrabPointer(3Xll) 

XKb - C Language X Interface 
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NAME 

XGrabPointer, XUngrabPointer^ XChangeActivePointerGrab - grab the pointer 
SYNTAX 

int XGrabPointeT(dispJay, grabjvindow, owner jvents, event jnask, pointer jnode, 
keyboard jnode, confine Jo, cursor, time) 
Display "^display; 
Window grabjvindow; 
Bool ownerjvents; 
unsigned int event jnask) 
int pointer jnode, keyboard jnode; 
Window confine Jo; 
Cursor cursor; 
Time time; 

XUngrabPointer(itsp%, time) 
Display ^display; 
Time time; 

XChangeActivePointerGrab (<lfisp%, event jnask, cursor, time) 
Display ^display; 
unsigned int event jnask; 
Cursor cursor; 
Time time; 

ARGUMENTS 

confine Jo Specifies the window to confine the pointer in or None. 

cursor Specifies the cursor that is to be displayed during the grab or 

None. 

display Specifies the connection to the XWBM server. 

event jnask Specifies which pointer events are reported to the client. The 
mask is the bitwise inclusive OR of the valid pointer event mask 
bits. 

grabjoindow Specifies the grab window. 

keyboardjnode Specifies further processing of keyboard events. You can pass 
" GrabModeSync or GiabModeAsync. 

ownerjvents Specifies a Boolean value that indicates whether the pointer 
events are to be reported as usual or reported with respect to 
the grab window if selected by the event mask. 

pointer jnode Specifies further processing of pointer events. You can pass 
GrabModeSync or GrabModeAsync. 

time Specifies the time. You can pass either a timestamp or Current- 

Time. 

DESCRIPTION 

The XGrabPointer function actively grabs control of the pointer and returns 
GrabSuccess if the grab was successful. Further pointer events are reported only 
to the grabbing client. XGrabPointer overrides any active pointer ^ab by this 
client. If owner_events is False, all generated pointer events are reported with 
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respect to grab_window and are reported only if selected by event__mask. If 
owner_events is True and if a generated pointer event would normally be 
reported to this client, it is reported as usual. Otherwise, the event is reported 
with respect to the grab_window and is reported only if selected by event^mask. 
For either value of owner_events, unreported events are discarded. 

If the pointer_mode is GrabModeAsync, pointer event processing continues as 
usual. If the pointer is currently frozen by this client, the processing of events for 
the pointer is resumed. If the pointer_mode is GiabModeSync, the state of the 
pointer, as seen by client applications, appears to freeze, and the XwiN server gen- 
erates no further pointer events until the grabbing client calls XAUowEvents or 
until the pointer grab is released. Actual pointer changes are not lost while the 
pointer is frozen; they are simply queued in the server for later processing. 

If the keyboard mode is GrabModeAsync, keyboard event processing is unaf- 
fected by activation of the grab. If the keyboard_mode is GrabModeSync, the 
state of the keyboard, as seen by client applications, appears to freeze, and the 
XwiN server generates no further keyboard events until the grabbing client calls 
XAllowEvents or until the pointer grab is released. Actual keyboard changes are 
not lost while the pointer is frozen; they are simply queued in the server for later 
processing. 

If a cursor is specified, it is displayed regardless of what window the pointer is 
in. If None is specified, the normal cursor for that window is displayed when the 
pointer is in grab^window or one of its subwindows; otherwise, the cursor for 
grab_window is displayed. 

If a confine__to window is specified, the pointer is restricted to stay contained in 
that window. The confine_to window need have no relationship to the 
grab_window. If the pointer is not initially in the confine_to window, it is 
warped automatically to the closest edge just before the grab activates and 
enter/leave events are generated as usual. If the confine Jto window is subse- 
quently reconfigured, the pointer is warped automatically, as necessary, to keep it 
contained in the window. 

The time argument allows you to avoid certain circumstances that come up if 
applications take a long time to respond or if there are long network dela)^. 
Consider a situation where you have two applications, both of which normally 
grab the pointer when clicked on. If both applications specify the timestamp 
from the event, the second application may wake up faster and successfully grab 
the pointer before the first application. The first application then will get an indi- 
cation that the other application grabbed the pointer before its request was pro- 
cessed. 

XGrabPointer generates EnterNotify and LeaveNotify events. 

Either if grab_window or confine_to window is not viewable or if the confine_to 
window lies completely outside the boundaries of the root window, XGrab- 
Pointer fails and returns GxabNotViewable. If the pointer is actively grabbed by 
some other client, it fails and rettirns AlreadyGrabbed. If the pointer is frozen 
by an active grab of another client, it fails and returns GrabFrozen. If the 
specified time is earlier than the last-pointer-grab time or later than the current 
XwiN server time, it fails and returns GrablnvalidTime. Otherwise, the last- 
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pointer-grab time is set to the specified time (CurrentTime is replaced by the 
current XwiN server time). 

XGrabPointer can generate BadCursor, BadValue, and BadWindow errors. 

The XUngiabPointer function releases the pointer and any queued events if this 
client has actively grabbed the pointer from XGrabPointer, XGrabButton, or 
from a normal button press. XUngrabPointer does not release the pointer if the 
specified time is earlier than the last-pointer-grab time or is later than the current 
XwiN server time. It also generates EnterNotify and LeaveNotify events. The 
XwiN server performs an UngiabPointer request automatically if the event win- 
dow or confine_to window for an active pointer grab becomes not viewable or if 
window reconfiguration causes the confinejo window to lie completely outside 
the boundaries of the root window. 

The XChangeActivePointerGrab function changes the specified dynamic parame- 
ters if the pointer is actively grabbed by the client and if the specified time is no 
earlier than the last-pointer-grab time and no later than the current XwiN server 
time. This function has no effect on the passive parameters of a XGrabButton. 
The interpretation of event_mask and cursor is the same as described in XGrab- 
Pointer. 

XChangeActivePointerGrab can generate a BadCursor and BadValue error. 
DIAGNOSTICS 

BadCursor A value for a Cursor argument does not name a defined Cursor. 

BadValue Some numeric value falls outside the range of values accepted 
by the request. Unless a specific range is specified for an argu- 
ment, the full range defined by the argument's type is accepted. 
Any argument defined as a set of alternatives can generate this 
error. 

BadWindow A value for a Window argument does not name a defined Win- 
dow. 

SEE ALSO 

XAUowEventsOXll), 

XGrabButtonOXll), 

XGrabKeyOXll), 

XGrabKeyboardOXll) 

Xlib - C Language X Interface 
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NAME 

XGrabServer, XUngrabServer - grab the server 

SYNTAX 

XGrabServer (display) 
Display *displajf; 

XUngrabServer(iii^ky) 
Display *display; 

ARGUMENTS 

display Specifies the connection to the XwiN server. 

DESCRIPTION 

The XGiabServer function disables processing of requests and close downs on all 
other connections than the one this request arrived on. You should not grab the 
XwiN server any more than is absolutely necessary. 

The XUngrabServer function restarts processing of requests and close downs on 
other connections. You should avoid grabbing the XwiN server as much as possi- 
ble. 

SEE ALSO 

XGrabButtonOXllX 

XGrabKeyOXll), 

XGrabKeyboardOXll), 

XGrabPointerOXll) 

Xlib - C Language X Interface 
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NAME 

XlfEvent, XChecklfEvent, XPeeklfEvent - check the event queue with a predicate 
procedure 

SYNTAX 

XlfEvent(display, event jelum, predicate, org) 
Display * display) 
XEvent ^eventj'etum; 
Bool {*predicate)0; 
char *«rg; 

Bool XCheckIfEvent(i2^2(iy, event jrelum, predicate, org) 
Display ^display) 
XEvent *event_retum; 
Bool i*predicate)0; 
char *arg; 

XPee\dfEyent(display, eventjetum, predicate, org) 
Display * display; 
XEvent *event_retum; 
Bool (*predicate)0; 
char *arg; 

ARGUMENTS 

arg Specifies the user-supplied argument that will be passed to the 

predicate procedure. 

display Specifies the connection to the XwiN server. 

eventjretum Returns either a copy of or the matched event's associated 
structure. 

predicate Specifies the procedure that is to be called to determine if the 

next event in the queue matches what you want. 

DESCRIPTION 

The XlfEvent function completes only when the specified predicate procedure 
returns Trae for an event, which indicates an event in the queue matches. 
XlfEvent flushes the output buffer if it blocks waiting for additional events. 
XlfEvent removes the matching event from the queue and copies the structure 
into the client-supplied XEvent structure. 

When the predicate procedure finds a match, XQiecklfEvent copies the matched 
event into the client-supplied XEvent structure and returns Trae. (This event is 
removed from the queue.) If the predicate procedure finds no match, 
XChecklfEvent returns Fake, and the output buffer will have been flushed. All 
earlier events stored in the queue are not discarded. 

The XPeeklfEvent function returns only when the specified predicate procedure 
returns Trae for an event. After the predicate procedure finds a match, 
XPeeklfEvent copies the matched event into the client-supplied XEvent structure 
without removing the event from the queue. XPeeklfEvent flushes the output 
buffer if it blocks waiting for additional events. 
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SEE ALSO 

XPutBackEventOXll) 

XNextEventOXll), 

XSendEventOXll) 

Xlib - C Language X Interface 
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NAME 

Xrmlnitialize, XrmParseCommand - initialize the Resource Manager and parse 
the cx>mmand line 

SYNTAX 

void XrmlnitializeO; 

void XrmParseCommand (ioioi^ose, table, table jx)unt, name, argcJnjDut, 
argvjnj)ut,) 
XrmDatabase ^database; 
XrmOptionDescList table; 
int table j:ount; 
char *nante; 
int *argcjnj)ut; 
char **argvjn out; 

ARGUMENTS 

argcjnj)ut 

argvjnjmt 

database 
name 
table 

tablejx)unt 
DESCRIPTION 

The Xrmlnitialize function initialize the resource manager. 

The XimParseCommand fimction parses an (argc, argv) pair according to the 
specified option table, loads recognized options into the specified database with 
type "String,'' and modifies the (argc, argv) pair to remove all recognized 
options. 

The specified table is used to parse the command line. Recognized entries in the 
table are removed from argv, and entries are made in the specified resource data- 
base. The table entries contain information on the option string, the option name, 
the style of option, and a value to provide if the option kind is Xrmoption- 
NoArg. The argc argument specifies the number of arguments in argv and is set 
to the remaining number of arguments that were not parsed. The name argu- 
ment should be the name of your application for use in building the database 
entry. The name argument is prefixed to the resourceName in the option table 
before storing the specification. No separating (binding) character is inserted. 
The table must contain either a period (.) or an asterisk (*) as the first character in 
each resourceName entry. To specify a more completely qualified resource name, 
the resourceName entry can contain multiple components. 



Specifies the number of argimients and returns the number of 
remaining arguments. 

Specifies a pointer to the command line arguments and returns 
the remaining arguments. 

Specifies a pointer to the resource database. 

Specifies the application name. 

Specifies the table of command line arguments to be parsed. 
Specifies the nimiber of entries in the table. 
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SEE ALSO 

XrmGetResourceOXll), 
XrmMergeDatabasesOXll), 
XrmPutResourceOXll), 
XrmUniqueQuarkOXll) 
Xlib - C Language X Interface 
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NAME 

XInstallColormap, XUninstallColormap, XListlnstalledColormaps - control color- 
maps 

SYNTAX 

XInstallColormap (iisp%, colormap) 
Display ^display; 
Colormap colormap 

XUninstallColormap (display, colormap) 
Display * display; 
Colormap colormap) 

Colormap *XListInstalledColormaps(^i^l!ay, w, numj'etum) 
Display * display; 
Window w) 
int *numj'etum; 

ARGUMENTS 

colormap 

display 
numjrelum 
w 

DESCRIPTION 

The XInstallColonnap function installs the specified colormap for its associated 
screen. All windows associated with this colormap immediately display with 
true colors. You associated the windows with this colormap when you created 
them by calling XCreateWindow, XCreateSimpleWindow, XChangeWindowAt- 
tributes, or XSetWindowColonnap. 

If the specified colormap is not already an installed colormap, the XwiN server 
generates a ColormapNotify event on each window that has that colormap. In 
addition, for every other colormap that is installed as a result of a call to XIn- 
stallColormap, the XwiN server generates a ColoimapNotify event on each win- 
dow that has that colormap. 

XInstallColonnap can generate a BadColor error. 

The XUninstallColormap function removes the specified colormap from the 
required list for its screen. As a result, the specified colormap might be imin- 
stalled, and the XwiN server might implicitly install or uninstall additional color- 
maps. Which colormaps get installed or uninstalled is server-dependent except 
that the required list must remain installed. 

If the specified colormap becomes uninstalled, the XwiN server generates a Color- 
mapNotify event on each window that has that colormap. In addition, for every 
other colormap that is installed or tminstalled as a result of a call to XUnin- 
stallColomiap, the XwiN server generates a ColormapNotify event on each win- 
dow that has that colormap. 



Specifies the colormap. 
Specifies the connection to the XwiN server. 
Returns the number of currently installed colormaps. 
Specifies the window that determines the screen. 
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XUninstallColonnap can generate a BadColor error. 

The XListlnstalledColonnaps function returns a list of the currently installed 
colormaps for the screen of the specified window. The order of the colormaps in 
the list is not significant and is no explicit indication of the required list. When 
the allocated list is no longer needed, free it by using XFree. 

XListlnstalledColomiaps can generate a BadWindow error. 

DIAGNOSTICS 

BadColor A value for a Colormap argument does not name a defined 

Colormap. 

BadWindow A value for a Window argument does not name a defined Win- 
dow. 

SEE ALSO 

Xlib - C Language X Interface 
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NAME 

XIntersectRegion, XUnionRegion, XUnionRectWithRegion, XSubtractRegion, 
XXorRegion^ XOffsetRegion, XShrinkRegion - region arthmetic 

SYNTAX 

XIntersectRegion (sra, srb, drjreiutn) 
Region sra, srb, drjeium) 

XUnionRegion (sra, srb, drjretum) 
Region sra, srb, drjreturn; 

XUnionRectWithRegionCr^ctengk, srcjegion, destjegion_return) 
XRectangle *rectangle; 
Region srcjegton; 
Region destregionretum; 

XSubtractRegion (sra, srb, drjetum) 
Region sra, srb, drjeturn) 

XXorRegion(sra, srb, drjelum) 
Region sra, srb, drjetum; 

XOffsetRegion(r, dx, dy) 
Region r; 
int dx, dy, 

XShrinkRegion(r, dx, dy) 
Region r; 
int dx, dy; 

ARGUMENTS 

desljegionjeturn 

Returns the destination region. 
drjetum Returns the result of the computation. 

dx 

dy Specify the x and y coordinates, which define the amount you 

want to move or shrink the specified region. 

r Specifies the region. 

rectangle Specifies the rectangle. 

sra 

srb Specify the two regions with which you want to perform the 

computation. 

srcjegion Specifies the source region to be used. 

DESCRIPTION 

The XIntersectRegion fimction computes the intersection of two regions. 

The XUnionRegion function computes the union of two regions. 

The XUnionRectWithRegion function updates the destination region from a 
union of the specified rectangle and the specified source region. 
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The XSubtractRegion function subtracts srb from sra and stores the results in 
dr_retum. 

The XXorRegion function calculates the difference between the union and inter- 
section of two regions. 

The XOffsetRegion function moves the specified region by a specified amount. 

The XShrinkRegion function reduces the specified region by a specified amount. 
Positive values shrink the size of the region, and negative values expand the 
region. 

SEE ALSO 

XCreateRegionOXll), 
XEmptyRegion(3Xll), 
Xlib " C Language X Interface 
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NAME 

XIntemAtom, XGetAtomName - create or return atom names 
SYNTAX 

Atom XInternAtom((ixsplay, atomjuime, ordyjf^exists) 
Display * display, 
char *atomjianie) 
Bool onlyjfyxists; 

char 'XGetAtomName (iii^lay, atom) 
Display ^display; 
Atom atom; 

ARGUMENTS 

atom Specifies the atom for the property name you want returned. 

atomjiame Specifies the name associated with the atom you want returned. 

display Specifies the connection to the XwiN server. 

onlyjf^exists Specifies a Boolean value that indicates whether XIntemAtom 
creates the atom. 

DESCRIPTION 

The XIntemAtom fimction returns the atom identifier associated with the 
specified atom_name string. If only_if_exists is False, the atom is created if it 
does not exist. Therefore, XIntemAtom can return None. You should use a 
null-terminated ISO Latin-1 string for atom^name. Case matters; the strings thing, 
Thing, and thinG all designate different atoms. The atom will remain defined even 
after the client's connection closes. It will become tmdefined only when the last 
connection to the XwiN server closes. 

XIntemAtom can generate BadAlloc and BadValue errors. 

The XGetAtomName function returns the name associated with the specified 
atom. To free the resulting string, call XFrce. 

XGetAtomName can generate a BadAtom error. 

DIAGNOSTICS 

BadAlloc The server failed to allocate the requested resource or server 

memory. 

BadAtom A value for an Atom argument does not name a defined Atom. 

BadValue Some numeric value falls outside the range of values accepted 
by the request. Unless a specific range is specified for an argu- 
ment, the full range defined by the argument's type is accepted. 
Any argument defined as a set of alternatives can generate this 
error. 

SEE ALSO 

XGetWindowPropertyOXll) 
Xlib - C Language X Interface 
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NAME 

XListFonts, XFreeFontNames, XListFontsWithlnfb, XFreeFontlnfo - obtain or free 
font names and information 

SYNTAX 

char ""^XListFonts (^iisp%, pattern, maxnames, adualjamntj^etum) 
Display * display; 
char * pattern; 
int maxnames; 
int * actual j:ountjetum; 

XFreeFontNames ( list ) 
char*its*[]; 

char **XListFontsWithInfo ((itsp%, pattern, maxnames, count_retum, infojeturn) 
Display * display; 
char ^pattern; 
int maxnames; 
int *countjetum; 
XFontStnlct **infojeturn; 

XFreeFontInfo(nflm€S, freejnfo, actualjxmnt) 
char **names; 
XFontStruct *freejnfo; 
int actual joount; 

ARGUMENTS 

actualj:ount Specifies the actual number of matched font names returned by 
XListFontsWithlnfo. 

actual j:ount_return 

Returns the actual number of font names. 

count jetum Returns the actual number of matched font names. 

display Specifies the connection to the XwiN server. 

infojeturn Returns a pointer to the font information. 

freejnfo Specifies the pointer to the font information returned by XList- 

FontsWithlnfo. 

list Specifies the array of strings you want to free. 

maxnames Specifies the maximum nimiber of names to be returned. 

names Specifies the list of font names returned by XListFontsWithlnfo. 

pattern Specifies the null-terminated pattern string that can contain 

wildcard characters. 

DESCRIPTION 

The XListFonts fimction returns an array of available font names (as controlled 
by the font search path; see XSetFontPath) that match the string you passed to 
the pattern argument. The string should be ISO Latin-1; uppercase and lowercase 
do not matter. Each string is terminated by an ASCII null. The pattern string 
can contain any characters, but each asterisk C^) is a wildcard for any number of 
characters, and each question mark (?) is a wildcard for a single character. The 
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client should call XFreeFontNames when finished with the result to free the 
memoiy. 

The XFreeFontNames function frees the array and strings returned by XlistFonts 
or XListFontsWithlnfo. 

The XListFontsWithlnfo function returns a list of font names that match the 
specified pattern and their associated font information. The list of names is lim- 
ited to size specified by maxnames. The information returned for each font is 
identical to what XLoadQueiyFont would return except that the per-character 
metrics are not returned. The pattern string can contain any characters, but each 
asterisk (*) is a wildcard for any ntmiber of characters, and each question mark 
(?) is a wildcard for a single character. To free the allocated name array, the 
client should call XFreeFontNames. To free the the font information array, the 
client should call XFreeFontlnfo. 

The XFreeFontlnfo function frees the the font information array. 

SEE ALSO 

XLoadFontOXll), 

XSetFontPathOXll) 

Xlib - C Language X Interface 
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NAME 

XLoadFont, XQueiyFont, XLoadQueiyFont, XFreeFont, XGetFontProperty, XUn- 
loadFont - load or unload fonts 

SYNTAX 

Font XLoadFont (iispky, name) 
Display ^display; 
char *name; 

XFontStruct '^XQueryFonHdisplay,f6ntJD) 
Display ^display; 
XID font JD; 

XFontStruct *XLoadQueryFont(ii^%, name) 
Display *display; 
char *name; 

XFreeFonHdisplay, font^struct) 
Display ^display; 
XFontStruct *fontjtruct; 

Bool XGetFontProperty(/ont_struci, atom, valuejeturn) 
XFontStruct *fontjtruct; 
Atom atom; 

unsigned long *viduejretum; 

XUnloadFont ((ixsp%, font) 
Display *display; 
Font font; 

ARGUMENTS 



atom 


Specifies the atom for the property name you want returned. 


display 


Specifies the connection to the XwiN server. 


font 


Specifies the font. 


fontJD 


Specifies the font ID or the GContext ID. 


fontjtrud 


Specifies the storage associated with the font. 




Specifies the GC. 


name 


Specifies the name of the font, which is a null-terminated string. 


valuejeturn 


Returns the value of the font property. 



DESCRIPTION 

The XLoadFont function loads the specified font and returns its associated font 
ID. The name should be ISO Latin-1 encoding; uppercase and lowercase do not 
matter. If XLoadFont was unsuccessful at loading the specified font, a BadName 
error results. Fonts are not associated with a particular screen and can be stored 
as a component of any GC. When the font is no longer needed, call XUnload- 
Font. 

XLoadFont can generate BadAUoc and BadName errors. 
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The XQueiyFont function returns a pointer to the XFontStruct structure, which 
contains information associated with the font. You can query a font or the font 
stored in a GC. The font ID stored in the XFontStruct structure will be the 
GContext ID, and you need to be careful when using this ID in other functions 
(see XGContextFromCC). To free this data, use XFreeFontlnfo. 

XLoadQueiyFont can generate a BadAlloc error. 

The XLoadQueiyFont function provides the most common way for accessing a 
font. XLoadQueiyFont both opens Qoads) the specified font and returns a 
pointer to the appropriate XFontStruct structure. If the font does not exist, 
XLoadQueiyFont returns NULL. 

The XFreeFont function deletes the association between the font resource ID and 
the specified font and frees the XFontStruct structure. The font itself will be 
freed when no other resource references it. The data and the font should not be 
referenced again. 

XFreeFont can generate a BadFont error. 

Given the atom for that property, the XGetFontProperty function returns the 
value of the specified font property. XGetFontProperty also returns False if the 
property was not defined or True if it was defined. A set of predefined atoms 
exists for font properties, which can be found in <Xll/Xatom.h>. This set con- 
tains the standard properties associated with a font. Although it is not 
guaranteed, it is likely that the predefined font properties will be present. 

The XUnloadFont function deletes the association between the font resource ID 
and the specified font. The font itself will be freed when no other resource refer- 
ences it. The font should not be referenced again. 

XUnloadFont can generate a BadFont error. 

DIAGNOSTICS 

BadAlloc The server failed to allocate the requested resource or server 

memory. 

BadFont A value for a Font or GContext argument does not name a 

defined Font. 

BadName A font or color of the specified name does not exist. 

SEE ALSO 

XListFontsOXll), 

XSetFontPathOXll) 

Xlib - C Language X Interface 
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NAME 

XLookupKeysym, XRefreshKeyboardMapping, XLookupString, XRebindKeyS)an 
~ handle keyboard input events 

SYNTAX 

KeySym yLookupKeysym(keyyutnt, index) 
XKeyEvent ^keyjvenV, 
int index; 

XRefreshKeyboardMapping(et;ent_map) 
XMappingEvent *eventjmp) 

int XLookupString(«^i_strMd, buffer jelum,hyiesjfuffer, keysymjetum, 
statusjnjmt) ~ 
XKeyEvent *event_struct; 
char *bufferjetum) 
int bytesjmffer; 
KeySym "^keysymjreturn) 
XComposeStatus *statusjnj)ut; 

XRebmdKeysymidisplay, keysym, list, modjx>unt, siring, bytes jtring) 
Display *display; 
Ke)?Sym keysym; 
KeySym list I] ; 
int mod_count; 
unsigned char * string; 
int bytes_string; 

ARGUMENTS 

buffer jetum Returns the translated characters. 

bytes Jfuffer Specifies the length of the buffer. No more than bytes_buffer of 
translation are returned. 

bytes^string Specifies the length of the string. 

display Specifies the connection to the XwiN server. 

event jmp Specifies the mapping event that is to be used. 

euentjstruct Specifies the key event structure to be used. You can pass 
XKeyPressedEvent or XKeyReleasedEvent. 

index Specifies the index into the KeySyms list for the event's Key- 

Code. 

keyjvent Specifies the KeyPress or KeyRelease event. 

keysym Specifies the KeySym that is to be . 

keysym return Returns the YjsySym computed from the event if this argument 
is not NULL. 

list Specifies the KeySyms to be used as modifiers. 

modjmmt Specifies the number of modifiers in the modifier list. 
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statu$Jnj)ut Specifies or returns the XComposeStatus structure or NULL. 

string Specifies a pointer to the string that is copied and will be 

returned by XLookupString. 

DESCRIPTION 

The XLookupKeysym function uses a given keyboard event and the index you 
specified to return the KeySym from the list that corresponds to the KeyCode 
member in the XKeyPressedEvent or XKeyReleasedEvent structure. If no 
KeySym is defined for the KeyCode of the event, XLookupKeysym returns 
NoSymboL 

The XRefreshKeyboardMapping function refreshes the stored modifier and key- 
map information. You usually call this function when a MappingNotify event 
with a request member of MappingKeyboard or MappingModifiier occurs. The 
result is to update Xlib's knowledge of the keyboard. 

The XLookupString function is a convenience routine that maps a key event to 
an ISO Latin-1 string, using the modifier bits in the key event to deal with shift, 
lock, and control. It returns the translated string into the user's buHer. It also 
detects any rebound KeySyms (see XRebindKeysym) and returns the specified 
bytes. XLookupString returns the length of the string stored in the tag buffer. If 
the lock modifier has the caps lock KeySym associated with it, XLookupString 
interprets the lock modifier to perform caps lock processing. 

If present (non-NULL), the XComposeStatus structure records the state, which is 
private to Xlib, that needs preservation across calls to XLookupString to imple- 
ment compose processing. 

The XRebindKeysym function can be used to rebind the meaning of a KeySym 
for the client. It does not redefine any key in the XwiN server but merely pro- 
vides an easy way for long strings to be attached to keys. XLookupString 
returns this string when the appropriate set of modifier keys are pressed and 
when the KeySym would have been used for the translation. Note that you can 
rebind a KeySym that may not exist. 

SEE ALSO 

XStringToKeysymOXll) 
Xlib - C Language X Interface 
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NAME 

XrmMergeDatabases, XrmGetFileDatabase, XrmPutFileDatabase, XrmGetStringDa- 
tabase - manipulate resource databases 

SYNTAX 

void XrmMergeDatabasesCsourc^jil^, target JOb) 
XrmDatabase source Jb, *targetjib; 

XrmDatabase XrmGetFileDatabase(^2enam^) 
char * filename; 

void XrmPutRleDatabase(iata2Kise, storedjib) 
XrmDatabase database; 
char * stored jib; 

XrmDatabase XrmGetStringDatabase(ia2ii) 
char *data; 

ARGUMENTS 

data 

database 
filename 
sourcejib 

storedjib 
target_db 

DESCRIPTION 

The XmiMeigeDatabases function merges the contents of one database into 
another. It may overwrite entries in the destination database. This function is 
used to combine databases (for example, an application specific database of 
defaults and a database of user preferences). The merge is destructive; that is, the 
source database is destroyed. 

The XrmGetFileDatabase function opens the specified file, creates a new resource 
database, and loads it with the specifications read in from the specified file. The 
specified file must contain lines in the format accepted by XnnPutLineResource. 
If it cannot open the specified file, XrmGetFileDatabase returns NULL. 

The XrmPutFileDatabase function stores a copy of the specified database in the 
specified file. The file is an ASCII text file that contains lines in the format that is 
accepted by XnnPutLineResource. 

The XnnGetStringDatabase function creates a new database and stores the 
resources specified in the specified null-terminated string. XimGetStringData- 
base is similar to XnnGetFileDatabase except that it reads the information out of 
a string instead of out of a file. Each line is separated by a new-line character in 
the format accepted by XrmPutlineResouice. 



Specifies the database contents using a string. 

Specifies the database that is to be used. 

Specifies the resource database file name. 

Specifies the resource database that is to be merged into the tar- 
get database. 

Specifies the file name for the stored database. 

Specifies a pointer to the resotirce database into which the 
source database is to be merged. 
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SEE ALSO 

XrmGetResourceOXl 1 ), 
XrmlnitializeOXll), 
XrmPutRe80urce(3Xll), 
XraiUniqueQuarkOXll) 
Xlib - C Language X Interface 
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NAME 



XMapWinow, XMapRaised, XMapSubwindows - map windows 



SYNTAX 



XMapWindow((l2sp2ay, w) 
Display ^display; 
Window w; 

XMapRaised(di$play, iv) 
Display *display; 
Window w; 

XMapSubwindows (iispky, w) 



DESCRIPTION 

The XMapWindow function maps the window and all of its subwindows that 
have had map requests. Mapping a window that has an unmapped ancestor does 
not display the window but marks it as eligible for display when the ancestor 
becomes mapped. Such a window is called imviewable. When all its ancestors 
are mapped, the window becomes viewable and will be visible on the screen if it 
is not obscured by another window. This function has no effect if the window is 
already mapped. 

If the override-redirect of the window is False and if some other client has 
selected SubstructureRedirectMask on the parent window, then the XwiN server 
generates a MapRequest event, and the XMapWindow fimction does not map 
the window. Otherwise, the window is mapped, and the XwiN server generates a 
MapNotify event. 

If the window becomes viewable and no earlier contents for it are remembered, 
the XwiN server tiles the window with its background. If the window's back- 
ground is imdefined, the existing screen contents are not altered, and the XwiN 
server generates zero or more Expose events. If backing-store was maintained 
while the window was immapped, no Expose events are generated. If backing- 
store will now be maintained, a full-window exposure is always generated. Oth- 
erwise, only visible regions may be reported. Similar tiling and exposure take 
place for any newly viewable inferiors. 

If the window is an InputOutput window, XMapWindow generates Expose 
events on each InputOutput window that it causes to be displayed. If the client 
maps and paints the window and if the client begins processing events, the win- 
dow is painted twice. To avoid this, first ask for E)q>ose events and then map 
the window, so the client processes input events as usual. The event list will 
include Expose for each window that has appeared on the screen. The client's 
normal response to an Expose event should be to repaint the window. This 
method usually leads to simpler programs and to proper interaction with win- 
dow managers. 
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Display *display, 
Window w; 



ARGUMENTS 

display 



Specifies the connection to the XwiN server. 
Specifies the window. 



w 
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XMap Window can generate a BadWindow error. 

The XMapRaised function essentially is similar to XMapWindow in that it maps 
the window and all of its subwindows that have had map requests. However, it 
also raises the specified window to the top of the stack. 

XMapRaised can generate a BadWindow error. 

The XMapSubwindows function maps all subwindows for a specified window in 
top-to-bottom stacking order. The XwiN server generates Expose events on each 
newly displayed window. This may be much more efficient than mapping many 
windows one at a time because the server needs to perform much of the work 
only once, for all of the windows, rather than for each window. 

XMapSubwindows can generate a BadWindow error. 

DIAGNOSTICS 

BadWindow A value for a Window ailment does not name a defined Win- 
dow. 

SEE ALSO 

XChangeWmdowAttributes(3Xll), 

XConfigureWindowOXl 1), 

XCreateWindowOXll), 

XDestroyWindowOXll), 

XRaiseWindowOXll), 

XUnmapWindowOXll) 

Xlib - C Language X Interface 
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NAME 



NextEvent, XPeekEvent, XWindowEvent, XCheckWindowEvent, XMaskEvent, 
XCheckMaskEvent, XCheckTypedEvent, XCheckTypedWindowEvent - select 
events by type 



XNextEvent(i{sp%, eventj'etum) 
Display ^display; 
XEvent ^eventj^etum; 

"XFeeliEvenHdisplay, eventjetum) 
Display * display', 
XEvent *event_retum; 

XWindowEvent(iispiIay, w, event jnask, eventjetum) 
Display ^display; 
Window w; 
long event jmsk; 
XEvent *event_retum; 

Bool XCheckWindowEvent(4ispbiy, w, event jnask, eventjetum) 
Display ^display; " 
Window w; 
long event jnask; 
XEvent *eventjetum; 

XtAasVEvenHdisplay, event jnask, eventjetum) 
Display ^display; 
long event jnask) 
XEvent *eventjetum; 

Bool XCheckMaskEvent(£fispky, event jnask, eventjetum) 
Display *display; 
long event jnask; 
XEvent *eventjetum; 

Bool XCheckT5^pedEvent(<iisp%, event Jype, eventjetum) 
Display ^display; 
int event Jype; 
XEvent *event return; 

Bool XCheckT3^pedWindowEvent((^ispiiy, w, event Jype, eventjetum) 
Display * display; 
Window w; 
int event Jype; 
XEvent "^eventjetum; 



SYNTAX 



ARGUMENTS 



display 
event mask 



Specifies the connection to the XwiN server. 
Specifies the event mask. 

Returns the matched event's associated structure. 



event retum 



10/89 



Page 1 



XNextEvent(3X11) 



XNextEvent(3X11) 



eventjype 



event return 



event return 



Returns the next event in the queue. 

Returns a copy of the matched event's associated structure. 

Specifies the event iy^ to be compared. 



w 



Specifies the window whose event you are interested in. 



DESCRIPTION 

The XNextEvent function copies the first event from the event queue into the 
specified XEvent structure and then removes it from the queue. If the event 
queue is empty, XNextEvent flushes the output buffer and blocks until an event 
is received. 

The XPeekEvent function returns the first event from the event queue, but it does 
not remove the event from the queue. If the queue is empty, XPeekEvent flushes 
the output buffer and blocks until an event is received. It then copies the event 
into the client-supplied XEvent structure without removing it from the event 
queue. 

The XWindowEvent function searches the event queue for an event that matches 
both the specified window and event mask. When it finds a match, XWin- 
dowEvent removes that event from the queue and copies it into the specified 
XEvent structtire. The other events stored in the queue are not discarded. If a 
matching event is not in the queue, XWindowEvent flushes the output buffer and 
blocks until one is received. 

The XCheckWindowEvent function searches the event queue and then the events 
available on the server connection for the first event that matches the specified 
window and event mask. If it finds a match, XCheckWindowEvent removes that 
event, copies it into the specified XEvent structure, and returns True. The other 
events stored in the queue are not discarded. If the event you requested is not 
available, XCheckWindowEvent returns False, and the output buffer will have 
been flushed. 

The XMaskEvent function searches the event queue for the events associated 
with the specified mask. When it finds a match, XMaskEvent removes that event 
and copies it into the specified XEvent structure. The other events stored in the 
queue are not discarded. If the event you requested is not in the queue, 
XMaskEvent flushes the output buffer and blocks until one is received. 

The XCheckMaskEvent function searches the event queue and then any events 
available on the server connection for the first event that matches the specified 
mask. If it finds a match, XCheckMaskEvent removes that event, copies it into 
the specified XEvent structure, and returns True. The other events stored in the 
queue are not discarded. If the event you requested is not available, XCheck- 
MaskEvent returns False, and the output buffer will have been flushed. 

The XCheckTypedEvent function searches the event queue and then any events 
available on the server connection for the first event that matches the specified 
type. If it finds a match, XCheckTypedEvent removes that event, copies it into 
the specified XEvent structure, and returns True. The other events in the queue 
are not discarded. If the event is not available, XCheckTypedEvent returns 
False, and the output buffer will have been flushed. 



Page 2 10/a9 



XNextEvent(3X11) 



XNextEvent(3X11) 



The XCheckTypedWindowEvent function searches the event queue and then any 
events available on the server connection for the first event that matches the 
specified type and window. If it finds a match, XCheckTypedWindowEvent 
removes the event from the queue, copies it into the specified XEvent structure, 
and returns True. The other events in the queue are not discarded. If the event 
is not available, XCheckTypedWindowEvent returns False, and the output 
buffer will have been flushed. 

SEE ALSO 

XlfEventOXll), 

XPutBackEventOXll), 

XSendEventOXll) 

Xlib - C Language X Interface 
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NAME 

XOpenDisplay, XCloseDisplay - connect or disconnect to XwiN server 
SYNTAX 

Display *XOpenDisp\ay{displayjtame) 
char *displayjtame; 

XCloseDisplay(iisp%) 
Display *display; 

ARGUMENTS 

display Specifies the connection to the XwiN server. 

displayjmme Specifies the hardware display name, which determines the 
" display and communications domain to be used. On a UNIX- 

based S3^tem, if the display_name is NULL, it defaults to the 
value of the DISPLAY environment variable. 

DESCRIPTION 

The XOpenDisplay function returns a Display structure that serves as the con- 
nection to the XwiN server and that contains all the information about that XwiN 
server. XOpenDisplay connects your application to the XwiN server. If the host- 
name is a host machine name and a single colon (:) separates the hostname and 
display number, XOpenDisplay connects using TCP streams. If the hostname is 
Unix and a single colon (:) separates it from the display number, XOpenDisplay 
connects using UNIX domain IPC streams. If the hostname is not specified, Xlib 
uses whatever it believes is the fastest transport. A single XwiN server can sup- 
port any or all of these transport mechanisms simultaneously. A particular Xlib 
implementation can support many more of these transport mechanisms. 

If successful, XOpenDisplay returns a pointer to a Display structure, which is 
defined in <Xll/XlibJi>. If XOpenDisplay does not succeed, it returns NULL. 
After a successful call to XOpenDisplay, all of the screens in the display can be 
used by the client. The screen number specified in the display_name argument is 
returned by the DefaultScreen macro (or the XDefaultScreen function). You can 
access elements of the Display and Screen structures only by using the informa- 
tion macros or functions. For information about using macros and functions to 
obtain information from the Display structure, see section Z2.1, Xlib — C Language 
X Interface, 

The XCloseDisplay function closes the connection to the XwiN server for the 
display specified in the Display structure and destroys all windows, resource IDs 
(Window, Font, Pixmap, Colormap, Cursor, and GContext), or other resources 
that the client has created on this display, unless the close-down mode of the 
resource has been changed (see XSetCloseDownMode). Therefore, these win- 
dows, resource IDs, and other resources should never be referenced again or an 
error will be generated. Before exiting, you should call XCloseDisplay explicitly 
so that any pending errors are reported as XCloseDisplay performs a final 
XSync operation. 

XCloseDisplay can generate a BadGC error. 
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SEE ALSO 

Xlib - C Language X Interface 
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NAME 

XParseGeometiy, XGeometry, XParseColor ~ parse window geometry and color 
SYNTAX 

int XParseGeometry (parsestring, xjetum, yjetum, width j^um, height jeturn) 
char ^parsestring; 
int *xjetum, *yjetum) 
int *widthjetum, *heightjretum; 

int XGeomeiry(display, screen, position, default jfosition, hwidth, fwidth, fheight, 
xadder, yadder, xjetum, y jeturn, widthjetum, heightjetum) 
Display *display; 
int screen; 

char *position, * default jmsition; 

unsigned int bwidth; 

unsigned int fwidth, fheight; 

int xadder, yadder; 

int *x jeturn, *y jeturn; 

int *vndthjeturn, ^height jeturn; 

Status XParseColor (i^ts;?%, colormap, spec, exact Jt^jetum) 
Display ^display; 
Colormap colormap; 
char *spec; 

XColor *exact_defjetum; 

ARGUMENTS 



hwidth 


Specifies the border width. 


colormap 


Specifies the colormap. 


position 




defaultjfosition 


Specify the geometry specifications. 


display 


Specifies the connection to the XwiN server. 


exactjiefjetum 


Returns the exact color value for later use and sets the DoRed, 


DoGreen, and DoBlue flags. 


fheight 




fwidth 


Specify the font height and width in pixels (increment size). 


parsestring 


Specifies the string you want to parse. 


screen 


Specifies the screen. 


spec 


Specifies the color name string; case is ignored. 


widthjetum 




heightjetum 


Return the width and height determined. 


xadder 




yadder 


Specify additional interior padding needed in the window. 


X return 
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yjetum Return the x and y offsets. 

DESCRIPTION 

By convention, X applications use a standard string to indicate window size and 
placement. XParseGeometry makes it easier to conform to this standard because 
it allows you to parse the standard window geometry. Specifically, this function 
lets you parse strings of the form: 

[=] [<vMth>x<hdgU>][{'¥'}<xoffse^^ 

The items in this form map into the arguments associated with this function. 
(Items enclosed in <> are integers, items in [] are optional, and items enclosed in 
{} indicate ''choose one of. Note that the brackets should not appear in the 
actual string.) 

The XParseGeometry function returns a bitmask that indicates which of the four 
values (width, height, xoffset, and yoffset) were actually found in the string and 
whether the x and y values are negative. By convention, ~0 is not equal to +0, 
because the user needs to be able to say "position the window relative to the 
right or bottom edge." For each value foimd, the corresponding argument is 
updated. For each value not foimd, the argument is left unchanged. The bits are 
represented by XValue, YValue, Width Value, HeightValue, XNegative, or 
YNegative and are defined in <Xll/XutilJi>. They will be set whenever one of 
the values is defined or one of the signs is set. 

If the function returns either the XValue or YValue flag, you should place the 
window at the requested position. 

You pass in the border width (bwidth), size of the increments fwidth and fheight 
(typically font width and height), and any additional interior space (xadder and 
yadder) to make it easy to compute the resulting size. The XGeometry function 
returns the position the window shotild be placai given a position and a default 
position. XGeometry determines the placement of a window using a geometry 
specification as specified by XParseGeometiy and the additional information 
about the window. Given a fully qualified default geometry specification and an 
incomplete geometry specification, XParseGeometiy returns a bitmask value as 
defined above in the XPaiseGeometiy call, by using the position argiunent. 

The returned width and height will be the width and height specified by 
default_position as overridden by any user-specified position. They are not 
affected by fwidth, fheight, xadder, or yadder. The x and y coordinates are com- 
puted by using the border width, the screen width and height, padding as 
specified by xadder and yadder, and the fheight and fwidth times the width and 
height from the geometry specifications. 

The XParseColor fimction provides a simple way to create a standard user inter- 
face to color. It takes a string specification of a color, t3rpically from a command 
line or XGetDefault option, and returns the corresponding red, green, and blue 
values that are suitable for a subsequent call to XAllocColor or XStoreColor. 
The color can be specified either as a color name (as in XAllocNamedColor) or as 
an initial sharp sign character followed by a numeric specification, in one of the 
following formats: 
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#RGB 
#RRGGBB 
#RRRGGGBBB 
#RRRRGGGGBBBB 



(4 bits each) 
(8 bits each) 
(12 bits each) 
(16 bits each) 



The R, G, and B represent single hexadecimal digits (both uppercase and lower- 
case). When fiewer than 16 bits each are specified, they represent the most- 
significant bits of the value. For example, #3a7 is the same as #3000a0007000. 
The colormap is used only to determine which screen to look up the color on. 
For example, you can use the screen's default colormap. 

If the initial character is a sharp sign but the string otherwise fails to fit the above 
formats or if the initial character is not a sharp sign and the named color does not 
exist in the server's database, XParseColor falls and returns zero. 

XParseColor can generate a BadColor error. 



DIAGNOSTICS 

BadColor 



A value for a Colormap aigument does not name a defined 
Colormap. 



SEE ALSO 



Xlib - C Language X Interface 
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NAME 

XPolygonRegion, XQipBox - generate regions 
SYNTAX 

Region XPolygDnRegion(pomfs, n, fiUjrule) 
XPoint paintsll; 
int n; 

int filljule; 

XClipBox(r^ rectjretum) 
Region r; 

XRectangle *rectj^etum; 
ARGUMENTS 

fiUjrule Specifies the fill-rule you want to set for the specified GC You 

can pass EvenOddRule or WindingRule. 

n Specifies the number of points in the polygon. 

points Specifies an array of points. 

r Specifies the region. 

rectjretum Returns the smallest enclosing rectangle. 

DESCRIPTION 

The XPolygonRegion function returns a region for the polygon defined by the 

points array. For an explanation of fill_rule, see XCieateGC. 

The XCUpBox function returns the smallest rectangle enclosing the specified 
region. 

SEE ALSO 

X/ft - C Language X Interface 
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NAME 

XPutBackEvent - put events back on the queue 

SYNTAX 

XPutBackEvent (display, event) 
Display *display; 
XEvent *event; 

ARGUMENTS 

display Specifies the connection to the XwiN server. 

event Specifies a pointer to the event. 

DESCRIPTION 

The XPutBackEvent function pushes an event back onto the head of the displa/s 
event queue by copying the event into the queue. This can be useful if you read 
an event and then decide that you would rather deal with it later. There is no 
limit to the number of times in succession that you can call XPutBackEvent. 

SEE ALSO 

XlfEventOXll), 

XNextEventOXll), 

XSendEventOXll) 

Xlib - C Language X Interface 
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NAME 

XPutlmage, XGetlmage, XGetSublmage - transfer images 
SYNTAX 

XPutImage(<ffspky, d, gc, image, srcjc, srcjf, destjc, destjf, width, height) 
Display * display) 
Drawable d; 
GCgc; 

Xlmage *image; 
int srcjc, srcj/; 
int destjc, destjy; 
unsigned int vndth, height] 

Xlmage *XGetImage (<ixspky, d, x, y, width, height, plane jnask, format) 
Display ^display; 
Drawable d; 
int X, y; 

unsigned int width, height; 
long planejnask; 
int format; 

Xlmage *XGetSubImage((itspifly, d, x, y, width, height, planejnask, format, 
destjmage, destjc, 
destjf) 
Display ^display; 
Drawable d; 
int X, y; 

unsigned int width, height; 
unsigned long planejnask; 
mi format; 
Xlmage *destjmage; 
int destjc, destjf; 

ARGUMENTS 

d Specifies the drawable. 

destjmage Specify the destination image. 

destjc 

destjf Specify the x and y coordinates, which are relative to the origin 

or the drawable and are the coordinates of the subimage or 
which are relative to the origin of the destination rectangle, 
specify its upper-left corner, and determine where the subimage 
is placed in the destination image. 

display Specifies the connection to the XwiN server. 

format Specifies the format for the image. You can pass XYBitmap, 

XYPixmap, or ZPixmap. 

gc Specifies the GC. 
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image 

planejnask 



Specifies the image you want combined with the rectangle. 
Specifies the plane mask. 

Specifies the offset in X from the left edge of the image defined 
by the Xlmage data structure. 

Specifies the offset in Y from the top edge of the image defined 
by the Xlmage data structure. 



src X 



srcjf 



width 
height 



Specify the width and height of the subimage, which define the 
dimensions of the rectangle. 



X 



y 



Specify the x and y coordinates, which are relative to the origin 
of the drawable and define the upper-left comer of the rectan- 
gle. 



DESCRIPTION 

The XPutlmage function combines an image in memory with a rectangle of the 
specified drawable. If XYBitmap format is used, the depth must be one, or a 
BadMatch error results. The foregroimd pixel in the GC defines the source for 
the one bits in the image, and the background pixel defines the source for the 
zero bits. For XYPixmap and ZPbanap, the depth must match the depth of the 
drawable, or a BadMatdi error results. The section of the image defined by the 
src_x, src_y, width, and height arguments is drawn on the specified part of the 
drawable. 

This fimction uses these GC components: function, plane-mask, subwindow- 
mode, clip-x-origin, clip-y-origin, and clip-mask. It also uses these GC mode- 
dependent components: foreground and background. 

XPutlmage can generate BadDiawable, BadCC, BadMatch, and BadValue 

errors. 

The XGetlmage function returns a pointer to an Xlmage structure. This struc- 
ture provides you with the contents of the specified rectangle of the drawable in 
the format you specify. If the format argument is XYPixmap, the image contains 
only the bit planes you passed to the plane^mask argument. If the plane_mask 
argument only requests a subset of the planes of the display, the depth of the 
returned image will be the number of planes requested. If the format argument 
is ZPixmap, XGetlmage returns as zero the bits in all planes not specified in the 
plane_mask argument. The function performs no range checking on the values in 
plane_mask and ignores extraneous bits. 

XGetlmage returns the depth of the image to the depth member of the Xlmage 
structure. The depth of the image is as specified when the drawable was created, 
except when getting a subset of the planes in XYPixmap format, when the depth 
is given by the number of bits set to 1 in plane_mask. 

If the drawable is a pixmap, the given rectangle must be wholly contained within 
the pixmap, or a BadMatch error results. If the drawable is a window, the win- 
dow must be viewable, and it must be the case that if there were no inferiors or 
overlapping windows, the specified rectangle of the window would be fully visi- 
ble on the screen and wholly contained within the outside edges of the window. 
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or a BadMatch error results. Note that the borders of the window can be 
included and read with this request. If the window has backing-store, the 
backing-store contents are returned for regions of the window that are obscured 
by noninferior windows. If the window does not have backing-store, the returned 
contents of such obscured regions are undefined. The retiuned contents of visible 
regions of inferiors of a different depth than the specified window's depth are 
also undefined. The pointer cursor image is not included in the returned con- 
tents. 

XGetlmage can generate BadDiawable, BadMatch, and BadValue errors. 

The XGetSublmage function updates dest_image with the specified subimage in 
the same manner as XGetlmage. If the format argtiment is XYPixmap, the image 
contains only the bit planes you passed to the plane_mask argimient. If the for- 
mat argument is ZPixmap, XGetSublmage returns as zero the bits in all planes 
not specified in the plane_mask argument. The function performs no range 
checking on the values in plane_mask and ignores extraneous bits. As a conveni- 
ence, XGetSublmage returns a pointer to the same Xlmage structure specified by 
dest_image. 

The depth of the destination Xlmage structure must be the same as that of the 
drawable. If the specified subimage does not fit at the specified location on the 
destination image, the right and bottom edges are clipped. If the drawable is a 
pixmap, the given rectangle must be wholly contained within the pixmap, or a 
BadMatch error results. If the drawable is a window, the window must be view- 
able, and it must be the case that if there were no inferiors or overlapping win- 
dows, the specified rectangle of the window would be fully visible on the screen 
and wholly contained within the outside edges of the window, or a BadMatch 
error results. If the window has backing-store, then the backing-store contents 
are returned for regions of the window that are obscured by noninferior win- 
dows. If the window does not have backing-store, the returned contents of such 
obscured regions are undefined. The returned contents of visible regions of infe- 
riors of a different depth than the specified window's depth are also undefined. 

XGetSublmage can generate BadDrawable, BadGC, BadMatdi, and BadValue 
errors. 

DIAGNOSTICS 

BadDrawable A value for a Drawable argument does not name a defined 
Window or Pixmap. 

BadGC A value for a GContext argument does not name a defined 



GContext. 



BadMatch 
BadMatch 



Some argument or pair of arguments has the correct type and 
range but feils to match in some other way required by the 
request. 



An InputOnly window is used as a Drawable. 



BadValue 



Some ntimeric value falls outside the range of values accepted 
by the request. Unless a specific range is specified for an argu- 
ment, the full range defined by the argument's type is accepted. 
Any argument defined as a set of alternatives can generate this 
error. 
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SEE ALSO 

Xlib - C Language X Interface 
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NAME 

XrmPutResource, XrmQPutResource, XrmPutStringResource, 

XrmQPutStringResource, XrmPutLineResource - store database resources 

SYNTAX 

void XrmPutResource(^ta2^as^, specifier, type, value) 
XrmDatabase ^database; 
char * specifier; 
char *type; 
Xrm Value *value; 

void XrmQPutResource (^abase, bindings, quarks, type, value) 
XrmDatabase *database; 
XrmBindingList bindings; 
XrmQuarkList quarks; 
XrmRepresentation type; 
Xrm Value *value; 

void XrmPutStringResource (iiatol^ase, specifier, value) 
XrmDatabase ^database; 
char * specifier; 
char *value; 

void XrmQPutSiTingResource(database, bindings, quarks, value) 
XrmDatabase *database; 
XrmBindingList bindings; 
XrmQuarkList quarks; 
char *vaiue; 

void XrmPutLineResourceCdflfflbflse, line) 
XrmDatabase *database; 
char *line; 

ARGUMENTS 



bindings 


Specifies a list of bindings. 


database 


Specifies a pointer to the resource database. 


line 


Specifies the resource value pair as a single string. A single 
colon (:) separates the name from the value. 


quarks 


Specifies the complete or partial name or the class list of the 
resource. 


specifier 


Specifies a complete or partial specification of the resource. 


type 


Specifies the tjrpe of the resource. 


value 


Specifies the value of the resource, which is specified as a string. 



DESCRIPTION 

If database contains NULL, XrmPutResource creates a new database and returns 
a pointer to it. XrmPutResource is a convenience function that calls 
XrmStringToBindingQuarkList followed by: 
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XrmQPutResource(database, bindings, quarks, XrmStringToQuark(type), value) 

If database contains NULL, XnnQPutResource creates a new database and 
returns a pointer to it. 

If database contains NULL, XrniPutStringResouice creates a new database and 
returns a pointer to it. XrmPutStringResouice adds a resource with the specified 
value to the specified database. Xn^utStringResource is a convenience routine 
that takes both the resource and value as null-terminated strings, converts them 
to quarks, and then calls XrmQPutResouice, using a ''String'' representation 
type. 

If database contains NULL, XrmQPutStringResource creates a new database and 
returns a pointer to it. XrmQPutStringResource is a convenience routine that 
constructs an XrmValue for the value string (by calling strlen to compute the 
size) and then calls XnnQPutResource, using a "String" representation type. 

If database contains NULL, XnnPutLineResource creates a new database and 
returns a pointer to it. XnnPutLineResource adds a single resource entry to the 
specified database. Any white space before or after the name or colon in the line 
argument is ignored. The value is terminated by a new-line or a NULL character. 
To allow values to contain embedded new-line characters, a 'W is recognized 
and replaced by a new-line character. For example, line might have the value 
"xterm*background:green\n". Null-terminated strings without a new line are also 
permitted. 

SEE ALSO 

XrmGetResource(3Xl 1), 
XrmInitialize(3Xll), 
XrmMergeDatabasesOXl 1), 
XrmUniqueQuarkOXll) 
Xlib - C Language X Interface 
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NAME 

XQueiyBestSize, XQueryBestTile, XQueryBestStipple - determine efficient sizes 
SYNTAX 

Status XQuery6estSize(ii^2ay, class, whidtjcreen, vndth, height, vndthjetum, 
height jretum) 
Display * display) 
int class; 

Drawable which^screen; 

unsigned int vHdth, height; 

unsigned int *widthjetum, *hdghtjetum; 

Status XQueryBestTile((iisp2ay, which^screen, width, height, widthjeium, 
height jretum) 
Display * display, 
Drawable whidtjcreen; 
unsigned int width, height; 
unsigned int *'widthjretum, *heightjetum; 

Status XQueryBestStipple ((fispky, whichjcreen, vndth, height, widthjetum, 
heightretum) 
Display * display; 
Drawable which_screen; 
unsigned int width, height ; 
unsigned int *vndthjretum, *height_retum; 

ARGUMENTS 

class Specifies the class that you are interested in. You can pass 

TileShape, CursorShape, or StippleShape. 

display Specifies the connection to the XwiN server. 

vndth 

height Specify the width and height. 

which^screen Specifies any drawable on the screen. 
vndthjretum 

height jetum Return the width and height of the object best supported by the 
display hardware. 

DESCRIPTION 

The XQueiyBestSize function returns the best or closest size to the specified size. 
For CursoiShape, this is the largest size that can be fully displayed on the screen 
specified by which_screen. For TileShape, this is the size that can be tiled 
fastest. For StippleShape, this is the size that can be stippled fostest. For Cur- 
sorShape, the drawable indicates the desired screen. For TileShape and Stip- 
pleShape, the drawable indicates the screen and possibly the window class and 
depth. An InputOnly window cannot be used as the drawable for TileShape or 
StippleShape, or a BadMatch error results. 

XQueiyBestSize can generate BadDrawable, BadMatch, and BadValue errors. 
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The XQueiyBestTile function returns the best or closest size, that is, the size that 
can be tiled fastest on the screen specified by which__screen. The drawable indi- 
cates the screen and possibly the window class and depth. If an 
InputOnly window is used as the drawable, a BadMatch error results. 

XQueiyBestTile can generate BadDiawable and BadMatch errors. 

XQueiyBestTile can generate BadDrawable and BadMatch errors. 

The XQueiyBestStipple function returns the best or closest size, that is, the size 
that can be stippled fastest on the screen specified by which_screen. The draw- 
able indicates the screen and possibly the window class and depth. If an 
InputOnly window is used as the drawable, a BadMatch error results. 

XQueiyBestStipple can generate BadDrawable and BadMatch errors. 

DIAGNOSTICS 

BadMatch An InputOnly window is used as a Drawable. 

BadDrawable A value for a Drawable argument does not name a defined 
Window or Pixmap. 

BadMatch The values do not exist for an InputOnly window. 

BadValue Some ntmieric value falls outside the range of values accepted 

by the request. Unless a specific range is specified for an argu- 
ment, the full range defined by the argument's type is accepted. 
Any argument defined as a set of alternatives can generate this 
error. 

SEE ALSO 

XCreateGCOXll), 

XSetArcModeOXll), 

XSetaipOriginOXl 1), 

XSetFillStyle(3Xll), 

XSetFontOXll), 

XSetLineAttributesOXll), 

XSetState(3Xll), 

XSetTile(3Xll) 

Xlib - C Language X Interface 
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NAME 

XQueiyColor, XQueryColors, XLookupColor - obtain color values 
SYNTAX 

XQueryColor (iisp%, colormap, defjnjmt) 
Display *^ifsplfly; 
Colormap colormap; 
XColor *defjnj>ut; 

XQueryColors (({ispZoy, colormap, def$jnj>ut, ncolors) 
Display *dzspiay; 
Colormap cobmtap; 
XColor def$Jnj>uil]; 
ini ncolors;" 

Status XLookupColor (ifsp2ay, colormap, color jiame, exacijiefjetum, 
screen Jiefjetum) 
Display *display]' 
Colormap colormap*, 
char *colorjume; 

XColor *exact_def_retum, *screenjiefjretum; 

ARGUMENTS 

colormap Specifies the colormap. 

color jtame Specifies the color name string (for example, red) whose color 
definition structure you want returned. 

defjnjmt Specifies and returns the RGB values for the pixel specified in 

the structure. 

defsjnj)ut Specifies and returns an array of color definition structures for 
the pixel specified in the structure. 

display Specifies the connection to the XwiN server. 

exact Jiefjetum Returns the exact RGB values. 

ncolors Specifies the number of XColor structures in the color definition 

array. 

saeen_defjetum Returns the closest RGB values provided by the hardware. 
DESCRIPTION 

The XQueryColor fimction returns the RGB values for each pixel in the XColor 
structures and sets the DoRed, DoCreen, and DoBlue flags. The XQueryColors 
fimction returns the RGB values for each pixel in the XColor structures and sets 
the DoRed, DoGreen, and DoBlue fiags. 

XQueryColor and XQueryColors can generate BadColor and BadValue errors. 

The XLookupColor function looks up the string name of a color with respect to 
the screen associated with the specified colormap. It returns both the exact color 
values and the closest values provided by the screen with respect to the visual 
type of the specified colormap. You should use the ISO Latin-1 encoding; upper- 
case and lowercase do not matter. XLookupColor returns nonzero if the name 
existed in the color database or zero if it did not exist. 
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DIAGNOSTICS 

BadColor A value for a Colormap argument does not name a defined 

Colormap. 

BadValue Some numeric value falls outside the range of values accepted 

by the request. Unless a specific range is specified for an argu- 
ment, the full range defined by the argtmient's type is accepted. 
Any argument defined as a set of alternatives can generate this 
error. 

SEE ALSO 

XAllocColoi<3Xll), 

XCreateColormapOXl 1 ), 

XStoreColorsOXll) 

Xlib - C Language X Interface 



Page 2 



10/89 



XQuery Pointer (3X11) 



XQueryPointer(3X11) 



NAME 

XQueryPointer - get pointer coordinates 
SYNTAX 

Bool XQueryPointer(<ii^%, w, rootjetum, child jetum, rootjcjetum, 
rootjfjetum, winjcjetum, mnjfjretum, maskjetum) 
Display ^display; 
Window w; 

Window *root_retum, *childjeturn; 
int *root_xjrelurn, *rootjfj'etum; 
int *winjcjretum, *winjijretum; 
unsigned int *masikjetum', 

ARGUMENTS 

childjreturn 

display 
maskjretum 

rootjetum 

rootjcjetum 
rootjfjetum 

w 

winjcjetum 
winjcjetum 

DESCRIPTION 

The XQueryPointer function returns the root window the pointer is logically on 
and the pointer coordinates relative to the root window's origin. If 
XQueryPointer returns False, the pointer is not on the same screen as the 
specified window, and XQueryPointer rettims None to child_return and zero to 
win_x_retum and win_y_retum. If XQueryPointer returns True, the pointer 
coordinates returned to win_x_retum and winjr_retum are relative to the origin 
of the specified window. In this case, XQueryPointer returns the child that con- 
tains the pointer, if any, or else None to childjreturn. 

XQueryPointer returns the current logical state of the keyboard buttons and the 
modifier keys in maskjretum. It sets mask_return to the bitwise inclusive OR of 
one or more of the button or modifier key bitmasks to match the current state of 
the mouse buttons and the modifier keys. 

XQueryPointer can generate a BadWindow error. 

DIAGNOSTICS 

BadWindow A value for a Window argument does hot name a defined Win- 
dow. 

SEE ALSO 

XGetWindowAttributesOXll), 

XQueryTreeOXll) 

Xlib - C Language X Interface 



Returns the child window that the pointer is located in, if any. 

Specifies the connection to the XwiN server. 

Returns the current state of the modifier Veys and pointer but- 
tons. 

Returns the root window that the pointer is in. 

Return the pointer coordinates relative to the root window's ori- 
gin. 

Specifies the window. 

Return the pointer coordinates relative to the specified window. 
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XQueryTree(3X11) 



NAME 

XQueryTree - query window tree information 
SYNTAX 

Status XQueryTree(/ii^lIay, w, rootjelum, parentjetum, children j'etum, 
nchildrenjreium ) 

Display ^display; 

Window w; 

Window *root_retum; 

Window *parentjretum; 

Window "^^ckildrenjetum; 

unsigned int *nchi1drenj'etum; 

ARGUMENTS 

chUdrenjreturn Returns a pointer to the list of children. 
display Specifies the connection to the XwiN server. 

nchildrenjetum Returns the number of children. 
parentjetum Returns the parent window. 
rooijretum Returns the root window. 

w Specifies the window whose list of children, root, parent, and 

number of children you want to obtain. 

DESCRIPTION 

The XQueryTree function returns the root ID, the parent window ID, a pointer to 
the list of children windows, and the number of children in the list for the 
specified window. The children are listed in current stacking order, from bottom- 
most (first) to topmost (last). XQueiyTree returns zero if it fails and nonzero if it 
succeeds. To free this list when it is no longer needed, use XFrce. 

BUGS 

This really should return a screen not a root window ID. 

SEE ALSO 

XGetWindowAttributesOXll), 

X(2ueryPointer(3Xll) 

Xlib - C Language X Interface 



10/89 



Page 1 



XRal8eWlndow(3X11) 



XRaimWindow(3X11) 



NAME 

XRaiseWindow, XLowerWindow, XCirculateSubwindows, XCirculateSubwin- 
dowsUp, XCirculateSubwindowsDown, XRestackWindows - change window 
stacking order 

SYNTAX 

XRaiseYIindow (disploj/, w) 
Display *dispUnf; 
Window w; 

XLowerWindow (^fispky, w) 
Display ^display; 
Window w; 

XCirculateSubwindows (display, w, direction) 
Display * display; 
Window w) 
int direction) 

XCirculateSubwindowsUp (display, w) 
Display *display; 
Window w; 

XCirculateSubwindowsDown(<iz^Ifly, w) 
Display ^display; 
Window w, 

XRestackWindows((^isp%, windows, nwindows); 
Display * display) 
Window windowsW) 
int nmndows; 

ARGUMENTS 

direction Specifies the direction (up or down) that you want to circulate 

the window. You can pass RaiseLowest or LowerHighest. 

display Specifies the connection to the XwiN server. 

nwindows Specifies the number of windows to be restacked. 

w Specifies the window. 

jvindotos Specifies an array containing the windows to be restacked. 

DESCRIPTION 

The XRaiseWindow function raises the specified window to the top of the stack 
so that no sibling window obscures it. If the windows are regarded as overlap- 
ping sheets of paper stacked on a desk, then raising a window is analogous to 
moving the sheet to the top of the stack but leaving its x and y location on the 
desk constant. Raising a mapped window may generate Expose events for the 
window and any mapped subwindows that were formerly obscured. 

If the override-redirect attribute of the window is False and some other client has 
selected SubstructureRedirectMask on the parent, the XwiN server generates a 
ConfigureRequest event, and no processing is performed. Otherwise, the win- 
dow is raised. 
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XRal8oWIndow(3X11) 



XRai80Window(3X11) 



XRaiseWindow can generate a BadWindow error. 

The XLowerWindow function lowers the specified window to the bottom of the 
stack so that it does not obscure any sibling windows. If the windows are 
regarded as overlapping sheets of paper stacked on a desk, then lowering a win- 
dow is analogous to moving the sheet to the bottom of the stack but leaving its x 
and y location on the desk constant. Lowering a mapped window will generate 
Expose events on any windows it formerly obscured. 

If the override-redirect attribute of the window is False and some other client has 
selected SubstnictureRedirectMask on the parent, the XwiN server generates a 
ConfigureRequest event, and no processing is performed. Otherwise, the win- 
dow is lowered to the bottom of the stack. 

XLowerWindow can generate a BadWindow error. 

The XCirculateSubwindows function circulates children of the specified window 
in the specified direction. If you specify RaiseLowest, XCirculateSubwindows 
raises the lowest mapped child (if any) that is occluded by another child to the 
top of the stack. If you specify LowerHighest, XCiiculateSubwindows lowers 
the highest mapped diild (if any) that occludes another child to the bottom of the 
stack. Exposure processing is then performed on formerly obscured windows. If 
some other client has selected SuDstmctureRedirectMask on the window, the 
XwiN server generates a CiiculateRequest event, and no further processing is 
performed. If a child is actually restacked, the XwiN server generates a 
CirculateNotify event. 

XCirculateSubwindows can generate BadValue and BadWindow errors. 

The XCiiculateSubwindowsUp function raises the lowest mapped child of the 
specified window that is partially or completely occluded by another child. Com- 
pletely imobscured children are not affected. This is a convenience function 
equivalent to XCirculateSubwindows with RaiseLowest specified. 

XCiiculateSubwindowsUp can generate a BadWindow error. 

The XCirculateSubwindowsDown function lowers the highest mapped child of 
the specified window that partially or completely occludes another child. Com- 
pletely unobscured children are not affected. This is a convenience function 
equivalent to XCirculateSubwindows with LowerHighest specified. 

XCirculateSubwindowsDown can generate a BadWindow error. 

The XRestackWindows function restacks the windows in the order specified, 
from top to bottom. The stacking order of the first window in the windows array 
is tmaffected, but the other windows in the array are stacked underneath the first 
window, in the order of the array. The stacking order of the other windows is 
not affected. For each window in the window array that is not a child of the 
specified window, a BadMatch error results. 

If the override-redirect attribute of a window is False and some other client has 
selected SubstnictureRedirectMask on the parent, the XwiN server generates 
ConfigureRequest events for each window whose override-redirect flag is not 
set, and no further processing is performed. Otherwise, the windows wiU be res- 
tacked in top to bottom order. 
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XRaiMWindow(3X11) 



XRestackWindows can generate BadWindow error. 
DIAGNOSTICS 

BadValue Some numeric value falls outside the range of values accepted 
by the request. Unless a specific range is specified for an argu- 
ment, the full range defined by the argument's type is accepted. 
Any argument defined as a set of alternatives can generate this 
error. 

BadWindow A value for a Window argument does not name a defined Win- 
dow. 

SEE ALSO 

XChangeWindowAttributesOXll), 

XConfigureWindowOXll), 

XCreateWindowOXll), 

XDestroyWindowOXll), 

XMapWindowOXll), 

XUnmapWindow(3Xll) 

Xlib - C Language X Interface 
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XReadBltmapFile (3X11 ) 



NAME 



XReadBltmapFile, XWriteBitmapRle, XCreatePixmapFromBitmapData, XCreateBit- 
mapFromData - manipulate bitmaps 



int XReadBitmapFile( ^^ispifly, d, fiJemme, widthjetum, heightjreturn, bitmapjretum, 
xjtotjeturn, yjtotjetum) 
Display ^display; 
Drawable d; 
char * filename; 

unsigned int *widthjetum, *heightjetum; 

Pixmap *bitmap_return; 

int *xJiotjeturn, *yJiotj'etum; 

int XWriteBitmapBle(ii^ifly, filename, bitmap, vndth, height, xjiot, yjiot) 
Display *display; 
char * filename; 
Pixmap bitmap; 
unsigned int irndth, height; 
int xjiot, yjiot; 

Pixmap XCreatePixmapFromBitmapData(<^ispifly, d, data, tmdth, height, fg, bg, depth) 
Display ^display; 
Drawable d; 
char *data; 

imsigned int width, height; 
unsigned long fg, bg; 
tinsigned int depth; 

Pixmap XCreateBitmapFromData(<izspi<^, d, data, tvidth, height) 
Display * display; 
Drawable d; 
char *data; 

unsigned int -width, height; 



SYNTAX 



ARGUMENTS 




operating-system dependent. 
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width 
height 



Specify the width and height. 



zvidthj'etum 

height jetum Return the width and height values of the read in bitmap file. 



xjwtj'etum 

yjiotjetum Return the hotspot coordinates. 
DESCRIPTION 

The XReadBitmapFile function reads in a file containing a bitmap. The file can 
be either in the standard X version 10 format (that is, the format used by X ver- 
sion 10 bitmap program) or in the X version 11 bitmap format. If the file cannot 
be opened, XReadBitmapFile returns BitmapOpenFailed. If the file can be 
opened but does not contain valid bitmap data, it returns BitmapFilelnvalid. If 
insufficient working storage is allocated, it returns BitmapNoMemoiy. If the file 
is readable and valid, it returns BitmapSuccess. 

XReadBitmapFile returns the bitmap's height and width, as read from the file, to 
width_retum and height_retum. It then creates a pixmap of the appropriate size, 
reads the bitmap data from the file into the pixmap, and assigns the pixmap to 
the caller's variable bitmap. The caller must nee the bitmap using XFieePixmap 
when finished. If name_x_YiOt and name_y_hot exist, XReadBitmapFile returns 
them to x__hot_retum and y_hot_retum; otherwise, it returns -1,-1. 

XReadBitmapFile can generate BadAUoc and BadDrawable errors. 

The XWriteBitmapFile fimction writes a bitmap out to a file. While XReadBit- 
mapFile can read in either X version 10 format or X version 11 format, 
XWriteBitmapFile always writes out X version 11 format. If the file cannot be 
opened for writing, it returns BitmapOpenFailed. If insufficient memory is allo- 
cated, XWriteBitmapFile returns BitmapNoMemoiy; otherwise, on no error, it 
returns BitmapSuccess. If x_hot and y_hot are not -1, -1, XWriteBitmapFile 
writes them out as the hotspot coordinates for the bitmap. 

XWriteBitmapFile can generate BadDrawable and BadMatch errors. 

The XCreatePixmapFiomBitmapData function creates a pixmap of the given 
depth and then does a bitmap-format XPutlmage of the data into it. The depth 
must be supported by the screen of the specified drawable, or a BadMatch error 
results. 

XCreatePixmapFromBitmapData can generate BadAUoc and BadMatch errors. 

The XCreateBitmapFromData function allows you to include in your C program 
(using #include) a bitmap file that was written out by XWriteBitmapFile (X ver- 
sion 11 format only) without reading in the bitmap file. The following example 
creates a gray bitmap: 



xjwt 
yjtot 



Specify where to place the hotspot coordinates (or -1,-1 if none 
are present) in the file. 
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#include "gray.bitmap" 
Pixmap bitmap; 

bitmap = XCreateBitmapFromData(display; window^ gray_bits, gray_widtlv gray_height); 

If insufficient working storage was allocated, XCreateBitmapFromData returns 
None. It is your responsibility to free the bitmap using XFreePixmap when 
finished. 

XCreateBitmapFromData can generate a BadAlloc error. 
DIAGNOSTICS 

BadAlloc The server failed to allocate the requested resource or server 

memory. 

BadDrawable A value for a Drawable argument does not name a defined 
Window or Pixmap. 

BadMatch An InputOnly window is used as a Drawable. 

SEE ALSO 

Xlib - C Language X Interface 
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XRecolorCur8or(3X11) 



NAME 

XRecolorCursor, XFreeCursor, XQueryBestCursor - manipulate cursors 
SYNTAX 

XRecolorCursor (ixspZay, cursor, foreground johr, background j:olor) 
Display ^display; 
Cursor cursor; 

XColor *foregroundjx>]or, *backgroundjx>lor; 

XFreeCuTsor (display, cursor) 
Display *dispUnf; 
Cursor cursor; 

Status XQueryBestCursor (iiispky, d, width, height, widthjeium, heighijelum) 
Display * display; 
Drawable d; 

unsigned int width, height; 

unsigned int *widthjelum, *heightjretum; 

ARGUMENTS 

background jxlor Specifies the RGB values for the background of the source. 
cursor Specifies the cursor. 

d Specifies the drawable, which indicates the screen. 

display Specifies the connection to the XwiN server. 

foreground_color Specifies the RGB values for the foreground of the source. 
width 

height Specify the width and height of the cursor for which you want 

the size information. 

widthj'eturn 

height jetum Return the best width and height that is closest to the specified 
width and height. 

DESCRIPTION 

The XRecoloiCursor function changes the color of the specified cursor, and if the 
cursor is being displayed on a screen, the change is visible immediately. 

XRecoloiCursor can generate a BadCuisor error. 

The XFieeCursor function deletes the association between the cursor resource ID 
and the specified cursor. The cursor storage is freed when no other resource 
references it. The specified cursor ID should not be referred to again. 

XFreeCursor can generate a BadCursor error. 

Some displays allow larger cursors than other displays. The XQueiyBestCursor 
fimction provides a way to find out what size cursors are actually possible on the 
display. It returns the largest size that can be displayed. Applications should be 
prepared to use smaller cursors on displays that cannot support large ones. 

XQueiyBestCursor can generate a BadDrawable error. 
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XR#colorCurMr(3X11) 



DIAGNOSTICS 

BadCuisor A value for a Cursor argument does not name a defined Cursor. 

BadDiawable A value for a Drawable argument does not name a defined 
Window or Pixmap. 

SEE ALSO 

XCreateFontCursorOXll), 

XDefineCusorOXll) 

Xlib - C Language X Interface 
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XReparentWindow(3X11 ) XReparentWindow(3X11 ) 



NAME 

XReparentWindow - reparent windows 
SYNTAX 

XReparentWindow(iisplfly, w, parent, x, y) 
Display *displajf; 
Window w; 
Window parent; 
int X, y; 

ARGUMENTS 

display 

parent 
w 

X 

y 

DESCRIPTION 

If the specified window is mapped, XReparentWindow automatically performs 
an UnmapWindow request on it, removes it from its current position in the 
hierarchy, and inserts it as the child of the specified parent. The window is 
placed in the stacking order on top with respect to sibling windows. 

After reparenting the specified window, XReparentWindow causes the XwiN 
server to generate a ReparentNotify event. The override redirect member 
returned in this event is set to the window's corresponding attribute. Window 
manager clients usually should ignore this window if this member is set to True. 
Finally, if the specified window was originally mapped, the XwiN server automat- 
ically performs a Map Window request on it. 

The XwiN server performs normal exposure processing on formerly obscured win- 
dows. The XwiN server might not generate Expose events for regions from the 
initial UnmapWindow request that are inunediately obscured by the final 
Map Window request. A BadMatch error results if: 

• The new parent window is not on the same screen as the old parent win- 
dow. , 

• The new parent window is the specified window or an inferior of the 
specified window. 

• The specified window has a ParentRelative background, and the new 
parent window is not the same depth as the specified window. 

XReparentWindow can generate BadMatdi and BadWindow errors. 

DIAGNOSTICS 

BadWindow A value for a Window argument does not name a defined Win- 
dow. 

SEE ALSO 

XChangeSaveSetOXll) 
Xlib - C Language X Interface 



Specifies the connection to the XwiN server. 
Specifies the parent window. 
Specifies the window. 

Specify the x and y coordinates of the position in the new 
parent window. 
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NAME 

XSaveContext, XFindContext, XDeleteContext, XUniqueContext - associative 
look-up routines 

SYNTAX 

int XSaveContext(display, w, context, data) 
Display *display; 
Window w; 
XContext context; 
caddr_t data) 

int XRndContext(ixsp%, w, context, datajetum) 
Display * display) 
Window w, 
XContext context', 
caddr_t *data_retum; 

int XDeleteContext(^fzsp%, w, context) 
Display * display) 
Window w) 
XContext context) 

XContext XUniqueContextO 



ARGUMENTS 

context Specifies the context type to which the data belongs. 

data Specifies the data to be associated with the window and type. 

datajreturn Returns a pointer to the data. 

display Specifies the connection to the XwiN server. 

w Specifies the window with which the data is associated. 
DESCRIPTION 



If an entry with the specified window and type already exists, XSaveContext 
overrides it with the specified context. The XSaveContext function returns a 
nonzero error code if an error has occurred and zero otherwise. Possible errors 
are XCNOMEM (out of memory). 

Because it is a return value, the data is a pointer. The XFindContext function 
returns a nonzero error code if an error has occurred and zero otherwise. Possi- 
ble errors are XCNOENT (context-not-found). 

The XDeleteContext fimction deletes the entry for the given window and type 
from the data structure. This function returns the same error codes that 
XFindContext returns if called with the same arguments. XDeleteContext does 
not free the data whose address was saved. 

The XUniqueContext function creates a unique context type that may be tised in 
subsequent calls to XSaveContext. 

SEE ALSO 

XUb - C Language X Interface 
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NAME 

XSelectlnput ~ select input events 
SYNTAX 

XSelectlnput w, event jmsk) 

Display *disphn/) 
Window w; 
long event jnask; 

ARGUMENTS 

display Specifies the connection to the XwiN server. 

event jnask Specifies the event mask. 

w Specifies the window whose events you are interested in. 

DESCRIPTION 

The XSelectlnput function requests that the XwiN server report the events associ- 
ated with the specified event mask. Initially, X will not report any of these 
events. Events are reported relative to a window. If a window is not interested 
in a device event, it usually propagates to the closest ancestor that is interested, 
unless the do not^propagate mask prohibits it. 

Setting the event-mask attribute of a window overrides any previous call for the 
same window but not for other clients. Multiple clients can select for the same 
events on the same window with the following restrictions: 

• Multiple clients can select events on the same window because their event 
masks are disjoint. When the XwiN server generates an event, it reports it to 
all interested clients. 

• Only one client at a time can select CirculateRequest, ConfiguieRequest, or 
MapRequest events, which are associated with the event mask Substruc- 
tureRediiectMask. 

• Only one client at a time can select a ResizeRequest event, which is associ- 
ated with the event mask ResizeRedirectMask. 

• Only one client at a time can select a ButtonPress event, which is associated 
with the event mask ButtonPiessMask. 

The server reports the event to all interested clients. 

XSelectlnput can generate a BadWindow error. 

DIAGNOSTICS 

BadWindow A value for a Window argument does not name a defined Win- 
dow. 

SEE ALSO 

Xlib - C Language X Interface 
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NAME 

XSetArcMode, XSetSubwindowMode, XSetGraphicsExposure - GC convience 
routines 

SYNTAX 

XSetArcModeidisplay, gc, arcjnode) 
Display ^display; 
GCgc; 
int arcjnode; 

XSetSubwindowMode(^i^Iay, gc, subwindowjnode) 
Display ^display; 
GQgc; 

int subwindowjnode; 

XSetGraphicsExposures(ii^2ay, gc, graphics jxposures) 
Display * display; 
GCgc; 

Bool graphics jxposures; 
ARGUMENTS 

arcjnode Specifies the arc mode. You can pass AicChord or ArdHeSUce. 

display Specifies the connection to the XwiN server. 

gc Specifies the GC. 

graphics jxposures 

Specifies a Boolean value that indicates whether you want Gra- 
phicsExpose and NoExpose events to be reported when calling 
XCopyArea and XCopyPlane with this GC 

subwindowjnode Specifies the subwindow mode. You can pass ClipByChildien 
or Indudelnferiors. 

DESCRIPTION 

The XSetArcMode function sets the arc mode in the specified GC. 

XSetArcMode can generate BadAlloc, BadGC, and BadValue errors. 

The XSetSubwindowMode function sets the subwindow mode in the specified 
GC 

XSetSubwindowMode can generate BadAUoc, BadGC, and BadValue errors. 

The XSetCiaphicsExposures function sets the graphics-exposures fiag in the 
specified GC. 

XSetCraphicsExposures can generate BadAUoc, BadGC, and BadValue errors. 
DIAGNOSTICS 

BadAUoc The server failed to allocate the requested resource or server 

memory. 

BadCC A value for a GContext argument does not name a defined 

GContext. 
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BadValue Some numeric value falls outside the range of values accepted 
by the request. Unless a specific range is specified for an argu- 
ment, the full range defined by the argument's type is accepted. 
Any argument defined as a set of alternatives can generate this 
error. 

SEE ALSO 

XCreateGCOXll), 

XQueryBestSize{3Xll), 

XSetaipQriginOXll), 

XSetFillStyle{3Xll), 

XSetFontOXll), 

XSetLineAttributesOXll), 

XSetState(3Xll), 

XSetTile(3Xll) 

Xlib - C Language X Interface 
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NAME 

XSetClassHint, XGetOassHint ~ set or get class hint 
SYNTAX 

XSetClassHint(itsp2ay, w, class Jiints) 
Display ^display-, 
Window w; 

XClassHint *classjtints; 

Status XGetQassHint(^ispi!ay, w, chssjiinisjeturn) 
Display ^display) 
Window w) 

XClassHint *class Jiints j^etum; 
ARGUMENTS 

class Jdnts Specifies a pointer to a XClassHint structure that is to be used. 

class Jiints j'etum 

Returns the XClassHint structure. 
display Specifies the connection to the XwiN server. 

TV Specifies the window. 

DESCRIPTION 

The XSetClassHint function sets the class hint for the specified window. 

XSetClassHint can generate BadAlloc and BadWindow errors. 

The XGetClassHint function returns the class of the specified window. To free 
res_name and res_class when finished with the strings, use XFiee. 

XGetClassHint can generate a BadWindow error. 

PROPERTY 

WM_CLASS 

DIAGNOSTICS 

BadAlloc The server failed to allocate the requested resource or server 

memory. 

BadWindow A value for a Window argtmtent does not name a defined Win- 
dow. 

SEE ALSO 

XSetCommand(3XllX 

XSetIconName(3Xll), 

XSetlconSizeHintsOXll), 

XSetNormalHintsOXll), 

XSetSizeHints(3Xll), 

XSetStandardPropertiesOXll), 

XSetTransientForHintOXll), 

XSetWMHintsOXll), 

XSetZoomHintsOXll), 

XStoreNameOXll) 

Xlib - C Language X Interface 
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NAME 

XSetClipQrigin^ XSetClipMask, XSetQipRectangles - GC convenience routines 
SYNTAX 

XSetClipQrigin(iisp2ay, gc, clipjc_prigin, clipjfj>rigin) 
Display * display, 
GCgc; 

int clipjcj)rigin, clipj^jorigin; 

XSetClipMask(iisp2ay, gc, pixmap) 
Display ^display; 
GCgq; 

Pixmap pixmap; 

XSetClipRectangles((lf^Iay, gc, clipjcj)rigin, clipj/j>rigin, rectangles, n, ordering) 
Display * display; 
GCgc; 

int clipjcj)rigin, clipj/j>rigin; 
XRectangle rectanglesU; 
int n; 

int ordering; 
ARGUMENTS 

display Specifies the connection to the XwiN server. 

clipjcj)rigin 

clip_yj>rigin Specify the x and y coordinates of the clip-mask origin. 

gc Specifies the GC. 

n Specifies the number of rectangles. 

ordering Specifies the ordering relations on the rectangles. You can pass 

Unsorted, YSorted, YXSorted, or YXBanded. 

pixmap Specifies the pixmap or None. 

rectangles Specifies an array of rectangles that define the clip-mask. 

DESCRIPTION 

The XSetClipOiigin function sets the clip origin in the specified GC. The dip- 
mask origin is interpreted relative to the origin of whatever destination drawable 
is specified in the graphics request. 

XSetClipOrigin can generate BadAlloc and BadGC errors. 

The XSetClipMask function sets the clip-mask in the specified GC to the 
specified pixmap. If the clip-mask is set to None, the pixels are are always 
drawn (regardless of the clip-origin). 

XSetClipMask can generate BadAlloc, BadGC, BadMatch, and BadValue 
errors. 

The XSelClipRectangles function changes the clip-mask in the specified GC to 
the specified list of rectangles and sets the clip origin. The output is clipped to 
remain contained within the rectangles. The clip-origin is interpreted relative to 
the origin of whatever destination drawable is specified in a graphics request. The 
rectangle coordinates are interpreted relative to the clip-origin. The rectangles 
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should be nonintersecting, or the graphics results will be undefined. Note that 
the list of rectangles can oe empty, which effectively disables output. This is the 
opposite of passing None as the clip-n\ask in XCreateGC, XChangeGC, and 
XSetClipMask. 

If known by the client, ordering relations on the rectangles can be specified with 
the ordering argument. This may provide faster operation by the server. If an 
incorrect ordering is specified, the XwiN server may generate a BadMatch error, 
but it is not required to do so. If no error is generated, the graphics results are 
undefined. Unsorted means the rectangles are in arbitrary order. YSorted 
means that the rectangles are nondecreasing in their Y origin. YXSorted addi- 
tionally constrains YSorted order in that all rectangles with an equal Y origin are 
nondecreasing in their X origin. YXBanded additionally constrains YXSorted by 
requiring that, for every possible Y scanline, all rectangles that include that scan- 
line have an identical Y origins and Y extents. 

XSetClipRectangles can generate BadAUoc, BadGC, BadMatch, and BadValue 
errors. 

DIAGNOSTICS 

BadAlloc The server failed to allocate the requested resource or server 

memory. 

BadGC A value for a GContext argument does not name a defined 

GContext. 

BadMatch Some argument or pair of argxmients has the correct type and 
range but fails to match in some other way required by the 
request. 

BadValue Some numeric value falls outside the range of values accepted 

by the request. Unless a specific range is specified for an argu- 
ment, the full range defined by the argimient's type is accepted. 
Any argument defined as a set of alternatives can generate this 
error. 

SEE ALSO 

XCreateGCOXll), 

XQueryBestSizeOXll), 

XSetArcMode(3Xll), 

XSetFillStyle(3Xll), 

XSetFontOXll), 

XSetLineAttributesOXll), 

XSetStateOXll), 

XSetTile(3Xll) 

Xlib - C Language X Interface 
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NAME 

XSetCloseDownMode, XKillQient - control clients 
SYNTAX 

XSetCloseDownMode (display, cbsejnode) 
Display *displajf; 
int dosejmie) 

XKillClient(iispZay, resource) 
Display ^display; 
XID resource; 

ARGUMENTS 

close jnode Specifies the client close-down mode. You can pass DestroyAU, 

RetainPennanent, or RetainTempoiaiy. 

display Specifies the connection to the XwiN server. 

resource Specifies any resotirce associated with the client that you want 

to destroy or AllTempoiaiy. 

DESCRIPTION 

The XSetCloseDownMode defines what will happen to the client's resources at 
connection close. A connection starts in DestroyAll mode. For information on 
what happens to the client's resources when the close_mode argument is Retain- 
Pemianent or RetainTempoiaiy, see section 2,6, Xlib — C Language X Interface. 

XSetCloseDownMode can generate a BadValue error. 

The XKillQient function forces a close-down of the client that created the 
resource if a valid resource is specified. If the dient has already terminated in 
either RetainPennanent or RetainTempoiaiy mode, all of the cHent's resources 
are destroyed. If AllTempoiaiy is specified, the resources of all clients that have 
terminated in RetainTempoiaiy are destroyed (see section 2.6, Xlib — C Language 
X Interface), This permits implementation of window manager facilities that aid 
debugging. A client can set its close-down mode to RetainTempoiaiy. If the 
client then crashes, its windows would not be destroyed. The programmer can 
then inspect the application's window tree and use the window manager to des- 
troy the zombie windows. 

XKillCUent can generate a BadValue error. 

DIAGNOSTICS 

BadValue Some numeric value falls outside the range of values accepted 
by the request. Unless a specific range is specified for an argu- 
ment, the full range defined by the argument's type is accepted. 
Any argument defined as a set of alternatives can generate this 
error. 

SEE ALSO 

Xlib - C Language X Interface 
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NAME 

XSetCommand - set command atom 
SYNTAX 

XSetCommand (ii^l^, w, argo, urge) 
Display ^display; 
Window w; 
char **argv; 
int argc; 

ARGUMENTS 

argc Specifies the number of arguments. 

argv Specifies the application's argument list. 

display Specifies the connection to the XwiN server. 

w Specifies the window. 
DESCRIPTION 

The XSetCommand function sets the command and arguments used to invoke 

the application. (T)rpically, argv is the argv array of your main program.) 

XSetCommand can generate BadAUoc and BadWindow errors. 

PROPERTY 

WM_COMMAND 

DIAGNOSTICS 

BadAlloc The server failed to allocate the requested resource or server 

memory. 

BadWindow A value for a Window argument does not name a defined Win- 
dow. 

SEE ALSO 

XSetClassHintOXll), 

XSetIconName(3Xll), 

XSetlconSizeHintsOXllX 

XSetNormalHintsOXll), 

XSetSizeHints(3Xll), 

XSetStandardPropertiesOXll), 

XSetTransientForHintOXll), 

XSetWMHints(3Xll), 

XSetZoomHintsOXll), 

XStoreName(3Xll) 

Xlib - C Language X Interface 
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NAME 

XSetErrorHandler, XGetErrorText, XDisplayName, XSetlOErrorHandler, XGetEr- 
rorDatabaseText - default error handlers 

SYNTAX 

XSetErrorHandler (handler) 
int i*handler)0; 

XGeiErrofText(display, code, buffer ^return, length) 
Display ^display, 
int code; 

char *hufferjetum; 
int lengfh; ~ 

char *XDisplayName(sinng) 
char "^string) 

XSetlOErrorHandlerChamller) 
int (*hand1er)Q; 

XGetErrorDatabaseText(iisp2ay, name, message, defauUjiring, buffer jretum, length) 
Display ^display; 
char *name, ^message; 
char *defaultjtring', 
char *bufferj^etum; 
int length; ~ 



ARGUMENTS 



bufferjretum 


Returns the error description. 


code 


Specifies the error code for which you want to obtain a descrip- 
tion. 


default^iring 


Specifies the default error message if none is found in the data- 


base. 


display 


Specifies the connection to the XwiN server. 


handler 


Specifies the program's supplied error handler. 


length 


Specifies the size of the buffer. 


message 


Specifies the type of the error message. 


name 


Specifies the name of the application. 


string 


Specifies the character string. 


DESCRIPTION 





Xlib generally calls the program's supplied error handler whenever an error is 
received. It is not called on BadName errors from OpenFont, LookupColor, or 
AllocNamedColor jrax>tocol requests or on BadFont errors from a QueiyFont 
protocol request. These errors generally are reflected back to the program 
through the procedural interface. Because this condition is not assumed to be 
fatal, it is acceptable for your error handler to return. However, the error handler 
should not call any fimctions (directly or indirectly) on the display that will gen- 
erate protocol requests or that will look for input events. 
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The XGetErrorText function copies a null-terminated string describing the 
specified error code into the specified buffer. It is recommended that you use 
this function to obtain an error description because extensions to Xlib may define 
their own error codes and error strings. 

The XDisplayName function rettims the name of the display that XOpenDisplay 
would attempt to use. If a NULL string is specified, XDisplayName looks in the 
environment for the display and returns the display name that XOpenDisplay 
would attempt to use. This makes it easier to report to the user precisely which 
display the program attempted to open when the initial connection attempt 
failed. 

The XSetlOErrorHandler sets the fatal I/O error handler. Xlib calls the 
program's supplied error handler if any sort of system call error occurs (for 
example, the connection to the server was lost). This is assumed to be a fatal 
condition, and the called routine should not return. If the I/O error handler does 
return, the client process exits. 

The XGetErrorDatabaseText function returns a message (or the default message) 
from the error message database. Xlib uses this function internally to look up its 
error messages. On a UNIX-based system, the error message database is 
/usr/lib/Xll/XEiTorDB . 

The name argimient should generally be the name of your application. The mes- 
sage argument should indicate which type of error message you want. Xlib uses 
three predefined message types to report errors (uppercase and lowercase 
matter): 

XProtoError The protocol error number is used as a string for the message 
argument. 

XlibMessage These are the message strings that are used internally by the 
library. 

XRequest The major request protocol number is used for the message 

argument. If no string is found in the error database, the 
default_string is returned to the buffer argument. 

SEE ALSO 

XSynchronize(3Xll) 

Xlib - C Language X Interface 
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NAME 

XSendEvent, XDisplayMotionBufferSize, XGetMotionEvents - send events 
SYNTAX 

Status XSendEvent(iisp2ay, w, propagate, event jnask, event jend) 
Display * display) 
Window w) 
Bool propagate) 
long event jnai^) 
XEvent *eoentjend) 

unsigned long XDisplayMotionBufferSize((iispZf}y) 
Display ^display) 

XTimeCoord '^XGetMotionEvents (4isp%, w, start, stop, neuentsjetum) 
Display ^display; 
Window w; 
Time start, stop; 
int *neuentsjretum; 

ARGUMENTS 

display 

eventjmsk 

event^send 

neventsjetum 

propagate 

start 
stop 

w 

DESCRIPTION 

The XSendEvent function identifies the destination window, determines which 
clients should receive the specified events, and ignores any active grabs. This 
fimction requires you to pass an event mask. For a discussion of the valid event 
mask names, see section 8.3. This function uses the w argument to identify the 
destination window as follows: 

• If w is PointerWindow, the destination window is the window that con- 
tains the pointer. 

• If w is InputFocus and if the focus window contains the pointer, the desti- 
nation window is the window that contains the pointer; otherwise, the desti- 
nation window is the focus window. 

To determine which clients should receive the specified events, XSendEvent uses 
the propagate aigument as follows: 



Specifies the connection to the XwiN server. 

Specifies the event mask. 

Specifies a pointer to the event that is to be sent. 

Returns the number of events from the motion history buffer. 

Specifies a Boolean value. 

Specify the time interval in which the events are returned from 
the motion history buffer. You can pass a timestamp or 
CunentTime. 

Specifies the window the event is to be sent to, PointcrWin- 
dow, or InputFocus. 
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• If event_mask is the empty set, the event is sent to the client that created the 
destination window. If that client no longer exists, no event is sent. 

• If propagate is False, the event is sent to every client selecting on destina- 
tion any of the event types in the event_mask argument. 

• If propagate is True and no clients have selected on destination any of the 
event types in event-mask, the destination is replaced with the closest ances- 
tor of destination for which some client has selected a type in event-mask 
and for which no intervening window has that type in its do-not- 
propagate-mask. If no such window exists or if the window is an ancestor 
of the focus window and InputFocus was originally specified as the desti- 
nation, the event is not sent to any clients. Otherwise, the event is reported 
to every client selecting on the final destination any of the types specified in 
event_mask. 

The event in the XEvent structure must be one of the core events or one of the 
events defined by an extension (or a BadValue error results) so that the XwiN 
server can correctly byte-swap the contents as necessary. The contents of the 
event are otherwise imaltered and imchecked by the XwiN server except to force 
send_event to True in the forwarded event and to set the serial number in the 
event correctly. 

XSendEvent returns zero if the conversion to wire protocol format failed and 
returns nonzero otherwise. XSendEvent can generate BadValue and BadWin- 
dow errors. 

The server may retain the recent history of the pointer motion and do so to a 
finer granularity than is reported by MotionNotify events. The XGetMo- 
tionEvents function makes this history available. 

The XGelMotionEvents function returns all events in the motion history buffer 
that fall between the specified start and stop times, inclusive, and that have coor- 
dinates that lie within the specified window (including its borders) at its present 
placement. If the start time is later than the stop time or if the start time is in the 
future, no events are returned. If the stop time is in the future, it is equivalent to 
specifying CuiTfentTinie. XGelMotionEvents can generate a Bad Window error. 

DIAGNOSTICS 

BadValue Some numeric value falls outside the range of values accepted 
by the request. Unless a specific range is specified for an argu- 
ment, the full range defined by the argument's type is accepted. 
Any argument defined as a set of alternatives can generate this 
error. 

BadWindow A value for a Window aigument does not name a defined Win- 
dow. 

SEE ALSO 

XlfEventOXll), 

XNextEventOXll), 

XPutBackEventOXll) 

Xlib - C Language X Interface 
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NAME 

XSetFillStyle, XSetRURule - GC convenience routines 
SYNTAX 

XSek¥\\\Sty\e(disphy, gc, filljtyle) 
Display * display) 
GCgc; 
ini fill^style; 

XSetFillRule(ixspZay, gc, fiUjule) 
Display *display; 
GCgc; 
int fUljule; 

ARGUMENTS 

display Specifies the connection to the XwiN server. 

filljule Specifies the fill-rule you want to set for the specified GC. You 

can pass EvenOddRule or WindingRule. 

filljtyle Specifies the fill-style you want to set for the specified GC. You 

can pass FillSolid, FillTiled, FillStippled, or FillOpaqueStip- 
pled. 

gc Specifies the GC. 

DESCRIPTION 

The XSetFillStyle function sets the fill-style in the specified GC. 
XSetFillStyle can generate BadAlloc, BadGC, and BadValue errors. 
The XSetFillRule function sets the fill-rule in the specified GC. 
XSetFillRule can generate BadAlloc, BadGC, and BadValue errors. 
DIAGNOSTICS 

BadAlloc The server failed to allocate the requested resource or server 

memory. 

BadCC A value for a GContext argument does not name a defined 

GContext. 

BadValue Some numeric value falls outside the range of values accepted 
by the request. Unless a specific range is specified for an argu- 
ment, the full range defined by the argument's type is accepted. 
Any argument defined as a set of alternatives can generate this 
error. 

SEE ALSO 

XCreateGCOXll), 

XQueryBestSize(3Xll), 

XSetArcMode(3Xll), 

XSetClipOriginOXllX 

XSetFontOXll), 

XSetUneAttributesOXll), 

XSetState(3Xll), 

XSetTile(3Xll) 

Xlib - C Language X Interface 



10/89 



Page 1 



XSetF6nt(3X11) 



XSetFont(3X11) 



NAME 

XSetFont - GC convenience routines 

SYNTAX 

XSetFont gc, font) 

Display *display) 
GCgp; 
Font font; 

ARGUMENTS 

display Specifies the connection to the XwiN server. 

font Specifies the font. 

gc Specifies the GC. 

DESCRIPTION 

The XSetFont function sets the current font in the specified GC. 
XSetFont can generate BadAUoc, BadFont, and BadGC errors. 
DIAGNOSTICS 

BadAUoc The server failed to allocate the requested resource or server 

memory. 

BadFont A value for a Font or GContext argument does not name a 

defined Font. 

BadGC A value for a GContext argument does not name a defined 

GContext. 

SEE ALSO 

XCreateGCOXll), 

XQueryBestSize(3Xll), 

XSetArcModeOXll), 

XSetClipQriginOXll), 

XSetFiUStyleOXll), 

XSetLineAttributes(3Xll), 

XSetStateOXll), 

XSetTile(3Xll) 

XIW - C Language X Interface 
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NAME 

XSetFontPath, XGetFontPath, XFreeFontPath - set, get, or free the font search 
path 

SYNTAX 

XSetFontPath ((display, directories, ndirs) 
Display *disphy; 
char ^^directories; 
int ndirs; 

char **XGetFontPath (<iisptoy, npaihsjetum) 
Display * display; 
int *npaths_retum; 



XFreeFontPath(/isO 
char **Ust; 



ARGUMENTS 

directories Specifies the directory path used to look for a font. Setting the 

path to the empty list restores the default path defined for the 
awin server. 

display Specifies the connection to the XwiN server. 

list Specifies the array of strings you want to free. 

ndirs Specifies the number of directories in the path. 

npaths_retum Returns the number of strings in the font path array. 
DESCRIPTION 

The XSetFontPath function defines the directory search path for font lookup. 
There is only one search path per XwiN server, not one per client. The interpreta- 
tion of the strings is operating system dependent, but they are intended to specify 
directories to be searched in the order listed. Also, the contents of these strings 
are operating system dependent and are not intended to be used by client appli- 
cations. Usually, the XwiN server is free to cache font information internally 
rather than having to read fonts from files. In addition, the XwiN server is 
guaranteed to fiush all cached information about fonts for which there currently 
are no explicit resource IDs allocated. The meaning of an error from this request 
is operating system dependent. 

XSetFontPath can generate a BadValue error. 

The XGetFontPath function allocates and returns an array of strings containing 
the search path. When it is no longer needed, the data in the font path should be 
freed by using XFreeFontPath. 

The XFreeFontPath function frees the data allocated by XGetFontPath. 
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DIAGNOSTICS 

BadValue Some numeric value falls outside the range of values accepted 

by the request. Unless a specific range is specified for an argu- 
ment, the full range defined by the argument's type is accepted. 
Any argument defined as a set of alternatives can generate this 
error. 

SEE ALSO 

XListFontOXll), 

XLoadFontsOXll) 

Xlib - C Language X Interface 



Page 2 



10/89 



XSetlconName(3X11) 



XSetlconName(3X11) 



NAME 

XSetlconName, XGetlconName - set or get icon names 
SYNTAX 

XSetlcoriName(displajf, w, iconjtante) 
Display *displciy) 
Window w; 
char *iconjtame; 

Status XGetIconName(itsp(tfy, w, iconjiamejretum) 
Display *dispUiy; 
Window w; 

char "^^iconjiamejretum) 
ARGUMENTS 

display Specifies the connection to the XwiN server. 

iconjiame Specifies the icon name, which should be a null-terminated 

string. 

iconjtamejetum Returns a pointer to the window's icon name, which is a null- 
terminated string. 

w Specifies the window. 

DESCRIPTION 

The XSetlconName fimction sets the name to be displayed in a window's icon. 

XSetlconName can generate BadAUoc and BadWindow errors. 

The XGetlconName function returns the name to be displayed in the specified 
window's icon. If it succeeds, it returns nonzero; otherwise, if no icon name has 
been set for the window, it returns zero. If you never assigned a name to the 
window, XGetlconName sets icon_name_return to NULL. When finished with 
it, a client must free the icon name string using XFxee. 

XGetlconName can generate a BadWindow error. 

PROPERTY 

WMJCON__NAME 

DIAGNOSTICS 

BadAUoc The server failed to allocate the requested resource or server 

memory. 

BadWindow A value for a Window argument does not name a defined Win- 
dow. 
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SEE ALSO 

XSetQassHintOXll), 

XSetCommand(3Xl 1), 

XSetlconSizeHintsOXll), 

XSetNormalHintsOXl 1 ), 

XSetSizeHintsOXll), 

XSetStandardPropertiesOXl 1), 

XSetTransientForHintOXll), 

XSetWMHintsOXll), 

XSetZoomHintsOXll), 

XStoreName(3Xll) 

Xlib - C Language X Interface 
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NAME 

XSetlconSizes, XGetlconSizes - set or get icon size hints 
SYNTAX 

XSetlconSizes (display, w, sizejist, count) 
Display ^display; 
Window w; 
XlconSize *sizejist; 
int count; 

Status XGetlconSizes (i2isp2^, w, sizejist jetum, count jetum) 
Display * display; 
Window w; 

XlconSize **sizejistjretum; 
int *countjretum; 

ARGUMENTS 

display Specifies the connection to the XwiN server. 

count Specifies the number of items in the size list. 

count jeium Returns the number of items in the size list. 
sizejist Specifies a pointer to the size list. 

sizejistjretum Returns a pointer to the size list. 
w Specifies the window. 

DESCRIPTION 

The XSetlconSizes function is used only by window numagers to set the sup- 
ported icon sizes. 

XSetlconSizes can generate BadAIloc and BadWindow errors. 

The XGetlconSizes fimction returns zero if a window manager has not set icon 
sizes or nonzero otherwise. XGetlconSizes should be called by an application 
that wants to find out what icon sizes would be most appreciated by the window 
manager under which the application is running. The application should then 
use XSetWMHints to supply the window manager with an icon pixmap or win- 
dow in one of the supported sizes. To free the data allocated in sizejist_return, 
use XFree. " 

XGetlconSizes can generate a BadWindow error. 

PROPERTY 

WMJCON^SIZE 

DIAGNOSTICS 

BadAIloc The server failed to allocate the requested resource or server 

memory. 

BadWindow A value for a Window argument does not name a defined Win- 
dow. 
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SEE ALSO 

XSetQassHintOXll), 

XSetCommandOXl 1), 

XSetIconName(3Xll), 

XSetNormalHintsOXll), 

XSetSizeHintsOXll), 

XSetStandardPropertiesOXll), 

XSetTransientForHintOXll), 

XSetWMHintsOXll), 

XSetZoomHintsOXll), 

XStoreNameOXll) 

Xlib - C Language X Interface 
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NAME 

XSetlnputFocus, XGetlnputFocus - control input focus 
SYNTAX 

XSetlnputFocus ((iisp%,/ocws, revert Jo, time) 
Display * display; 
Window focus ) 
int revert Jo; 
Time time; 

XGetlnputFocus (<ltsptoy, focus jetum, revert Jo jetum) 
Display *display; 
Window *focusjeturn; 
int *revertJojeturn; 

ARGUMENTS 

display Specifies the connection to the XwiN server. 

focus Specifies the window, PointerRoot, or None. 

focus jeturn Returns the focus window, PointerRoot, or None. 

revert Jo Specifies where the input focus reverts to if the window 

becomes not viewable. You can pass RevertToParent, Revert- 
ToPointerRoot, or RevertToNone. 

revert Jo jeturn Returns the current focus state (RevertToParent, RevertToPoin- 
terRoot, or RevertToNone). 

time Specifies the time. You can pass either a timestamp or Current- 

Time. 

DESCRIPTION 

The XSetlnputFocus function changes the input focus and the last-focus-change 
time. It has no effect if the specified time is earlier than the current last-focus- 
change time or is later than the current XwiN server time. Otherwise, the last- 
focus-change time is set to the specified time (CuirentTime is replaced by the 
current XwiN server time). XSetlnputFocus causes the XwiN server to generate 
Focusin and FocusOut events. 

Depending on the focus argument, the following occurs: 

• If focus is None, all keyboard events are discarded until a new focus win- 
dow is set, and the revert_to argument is ignored. 

• If focus is a window, it becomes the keyboard's focus window. If a gen- 
erated keyboard event would normally be reported to this window or one 
of its inferiors, the event is reported as usual. Otherwise, the event is 
reported relative to the focus window. 

• If focus is PointerRoot, the focus window is dynamically taken to be the 
root window of whatever screen the pointer is on at each keyboard event. 
In this case, the revert_to argument is ignored. 

The specified focus window must be viewable at the time XSetlnputFocus is 
called, or a BadMatch error results. If the focus window later becomes not view- 
able, the XwiN server evaluates the revert_to argument to determine the new 
focus window as follows: 
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• If revert_to is RevertToParent, the focus reverts to the parent (or the closest 
viewable ancestor), and the new revertjto value is taken to be RevcrtTo- 
None. 

• If revertjto is ReveitToPointerRoot or RevertToNone, the focus reverts to 
PointerRoot or None, respectively. When the focus reverts, the XwiN 
server generates Focusin and FocusOut events, but the last-foctis-<:hange 
time is not affected. 

XSetlnputFocus can generate BadMatch, BadVaiue, and BadWindow errors. 

The XGetlnputFocus function returns the focus window and the current focus 
state. 

DIAGNOSTICS 

BadVaiue Some numeric value falls outside the range of values accepted 
by the request. Unless a specific range is specified for an argu- 
ment, the full range defined by the argument's tyipe is accepted. 
Any argument defined as a set of alternatives can generate this 
error. 

BadWindow A value for a Window ailment does not name a defined Win- 
dow. 

SEE ALSO 

XWarpPointer(3Xll) 

Xlib - C Language X Interface 
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NAME 

XSetLineAttribute, XSetDashes - GC convenience routines 
SYNTAX 

XSetLineAttributes(^isp2ay, gc, linejmdth, line_style, capjtyle, joinjtyk) 
Display * display; 
GCgc; 

unsigned int linejmdth; 
int line^style; 
int capjtyle; 
ini join jtyle; 

XSetDdLshes(display, gc, dashjffsel, dashjist, n) 
Display *displmf; 
GCgc; 

int dash jff set; 
char dashjistl]; 
int n; 

ARGUMENTS 

capjtyle 



dashjist 

dashj>ffset 

display 

joinjtyk 
linejtyle 



linejmdth 
n 

DESCRIPTION 

The XSetLineAttributes function sets the line drawing components in the 
specified GC. 

XSetLineAttributes can generate BadAlloc, BadCC, and BadValue errors. 

The XSetDashes function sets the dash-offset and dash-list attributes for dashed 
line styles in the specified GC. There must be at least one element in the 
specified dash_list, or a BadValue error results. The initial and alternating ele- 
ments (second, fourth, and so on) of the dash_list are the even dashes, and the 
others are the odd dashes. Each element speci&s a dash length in pixels. All of 



Specifies the line-style and cap-style you want to set for the 
specified GC. You can pass CapNotLast, CapButt, CapRound, 
or CapProjecting. 

Specifies the dash-list for the dashed line-style you want to set 
for the specified GC. 

Specifies the phase of the pattern for the dashed line-style you 
want to set for the specified GC. 

Specifies the connection to the XwiN server. 

Specifies the GC. 

Specifies the line join-style you want to set for the specified GC. 
You can pass JoinMiter, JoinRound, or JoinBevel. 

Specifies the line-style you want to set for the specified GC. 
You can pass LineSolid, lineOnOffDash, or 
lineDoubleDash . 

Specifies the line-width you want to set for the specified GC. 
Specifies the number of elements in dash^list. 
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the elements must be nonzero, or a BadValue error results. Specifying an odd- 
length list is equivalent to specifying the same list concatenated with itsdf to pro- 
duce an even-length list. 

The dash-offset defines the phase of the pattern, specifying how many pixels into 
the dash-list the pattern should actually begin in any single graphics request. 
Dashing is continuous through path elements combined with a join-style but is 
reset to the dash-offset each time a cap-style is applied at a line endpoint. 

The unit of measure for dashes is the same for the ordinary coordinate system. 
Ideally, a dash length is measured along the slope of the line, but implementa- 
tions are only required to match this ideal for horizontal and vertical lines. Fail- 
ing the ideal semantics, it is suggested that the length be measured along the 
major axis of the line. The major axis is defined as the x axis for lines drawn at 
an angle of between -45 and +45 degrees or between 315 and 225 degrees from 
the x axis. For all other lines, the major axis is the y axis. 

XSetDashes can generate BadAlloc, BadGC, and BadValue errors. 

DIAGNOSTICS 

BadAlloc The server failed to allocate the requested resource or server 

memory. 

BadGC A value for a GContext argument does not name a defined 

GContext. 

BadValue Some numeric value falls outside the range of values accepted 
by the request. Unless a specific range is specified for an argu- 
ment, the full range defined by the argimient's type is accepted. 
Any argument defined as a set of alternatives can generate this 
error. 

SEE ALSO 

XCreateGCOXll), 

XQueryBestSize(3Xll), 

XSetArcModeOXll), 

XSetaipOriginOXll), 

XSetFiUStyleOXll), 

XSetFont(3Xll), 

XSetState(3Xll), 

XSetTile{3Xll) 

Xlib - C Language X Interface 
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NAME 

XSetNormalHints, XGetNormalHints - set or get normal state hints 
SYNTAX 

XSetNormalHints(ii^ifly^ w, hints) 
Display ^display; 
Window «?; 
XSizeHints *hints; 

Status XGetNormalHints (^fisplny, w, hints_retum) 
Display * display; 
Window w; 

XSizeHints *hintsjetum; 
ARGUMENTS 

display Specifies the connection to the XwiN server. 

hints Specifies a pointer to the size hints for the window in its normal 

state. 

hints jetum Returns the size hints for the window in its nonnal state. 
w Specifies the window. 

DESCRIPTION 

The XSetNormalHints function sets the size hints structure for the specified win- 
dow. Applications use XSetNormalHints to inform the window manager of the 
size or position desirable for that window. In addition, an application that wants 
to move or resize itself should call XSetNormalHints and specify its new desired 
location and size as well as making direct Xlib calls to move or resize. This is 
because window managers may ignore redirected configure requests, but they 
pay attention to property changes. 

To set size hints, an application not only must assign values to the appropriate 
members in the hints structure but also must set the flags member of the struc- 
ture to indicate which information is present and where it came from, A call to 
XSetNormalHints is meaningless, unless the fiags member is set to indicate 
which members of the structure have been assigned values. 

XSetNormalHints can generate BadAlloc and BadWindow errors. 

The XGetNormalHints function returns the size hints for a window in its normal 
state. It returns a nonzero status if it succeeds or zero if the application specified 
no normal size hints for this window. 

XGetNoimalHints can generate a BadWindow error. 

PROPERTY 

WM_NORMAL_HINTS 

DIAGNOSTICS 

BadAlloc The server failed to allocate the requested resource or server 

memory. 

BadWindow A value for a Window argument does not name a defined Win- 
dow. 
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SEE ALSO 

XSetC6mmand(3Xl 1), 

XSetIconName(3Xll), 

XSetIcx)nSizeHints(3Xll), 

XSetSizeHintsOXll), 

XSetStandardPropertiesOXll), 

XSetWMHintsOXll), 

XSetZoomHints(3Xll), 

XStoreName(3Xll) 

Xtib - C Language X Interface 
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NAME 

XSetPointerMapping, XGetPointerMapping ~ manipulate pointer settings 
SYNTAX 

int XSetPointerMapping (<ifsp%, map, nmap) 
Display ^display; 
unsigned char mapU; 
int nmap; 

int XGetPointerMapping (display, mapjetum, nmap) 
Display ^display) 
unsigned char map_retuml]; 
int nmap; 

ARGUMENTS 

display Specifies the connection to the XwiN server. 

map Specifies the mapping list. 

mapjetum Returns the mapping list. 

nmap Specifies the nimiber of items in the mapping list. 

DESCRIPTION 

The XSetPointerMapping fimction sets the mapping of the pointer. If it 
succeeds, the XwiN server generates a MappingNotify event, and XSetPointer- 
Mapping returns MappingSuccess. Elements of the list are indexed starting 
from one. The length of the list must be the same as XGetPointerMapping 
would return, or a BadValue error results. The index is a core button number, 
and the element of the list defines the effective number. A zero element disables 
a button, and elements are not restricted in value by the ntimber of physical but- 
tons. However, no two elements can have the same nonzero value, or a Bad- 
Value error results. If any of the buttons to be altered are logically in the down 
state, XSetPointerMapping returns MappingBusy, and the mapping is not 
changed. 

XSetPointerMapping can generate a BadValue error. 

The XGetPointerMapping function returns the current mapping of the pointer. 
Elements of the list are indexed starting from one. XGetPointerMapping returns 
the nimiber of physical buttons actually on the pointer. The nominal mapping for 
a pointer is the identity mapping: map[i]=i. The nmap argument specifies the 
length of the array where the pointer mapping is returned, and only the first 
nmap elements are returned in map return. 

DIAGNOSTICS 

BadValue Some numeric value falls outside the range of values accepted 
by the request. Unless a specific range is specified for an argu- 
m.ent, the full range defined by the argument's type is accepted. 
Any argument defined as a set of alternatives can generate this 
error. 

SEE ALSO 

XChangeKeyboardControl(3Xll), 
XChangeKeyboardMappingOXl 1) 
XliJb - C Language X Interface 
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NAME 

XSetScreenSaver, XForceScreenSaver, XActivateScreenSaver, XResetScreenSaver, 
XGetScreenSaver - manipulate the screen saver 

SYNTAX 

XSetScreenSaver(ii5p2ay, timeout, interval, prefer Jthnking, allow exposures) 
Display *disf}lay; 
int timeout, interval) 
int prefer Jflanking; 
int dlowjxposures; 

XForceScreenSaverCizsptoy, mode) 
Display ^display; 
int mode; 

XActivateScreenSaver {display) 
Display *display; 

XResetScreenSaver {display) 
Display ^display; 

XGetScreenSaver (display, timeout jeturn, interval jretum, prefer JflanJdng retum, 
allau}_exposuresjretum) " 
Display * display, 

int Himeoutjetum, ^interval jeturn; 
int *preferj)lan}dng jeturn ', 
int *allowjxposuresjetum; 

ARGUMENTS 

allowjxposures Specifies the screen save control values. You can pass DontAl- 
lowExposuies, AllowExposures, or DefaultExposures. 

allowjxposures jeturn 

Returns the current screen save control value (DontAllowExpo- 
sures, AllowExposures, or DefaultExposures). 

display Specifies the connection to the XwiN server. 

interval Specifies the interval between screen saver alterations. 

intervaljetum Returns the interval between screen saver invocations. 

mode Specifies the mode that is to be applied. You can pass Screen- 

Saver Active or ScreenSaverReset. 

prefer Jolanldng Specifies how to enable screen blanking. You can pass 
DontPreferBlanking, PreferBlanking, or DefaullBlanking. 

prefer JflatiMngjetum 

" Returns the current screen blanking preference (DontPrefeiy 
Blanking, PreferBlanking, or DefaultBlanldng). 

timeout Specifies the timeout, in seconds, until the screen saver turns on. 

timeout return Returns the timeout, in minutes, until the screen saver turns on. 
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DESCRIPTION 

Timeout and interval are specified in seconds. A timeout of 0 disables the screen 
saver, and a timeout of -1 restores the default. Other negative values generate a 
BadValue error. If the timeout value is nonzero, XSetScreenSaver enables the 
screen saver. An interval of 0 disables the random-pattern motion. If no input 
from devices (keyboard, mouse, and so on) is generated for the specified number 
of timeout seconds once the screen saver is enabled, the screen saver is activated. 

For each screen, if blanking is preferred and the hardware supports video blank- 
ing, the screen simply goes blank. Otherwise, if either exposures are allowed or 
the screen can be regenerated without sending Expose events to clients, the 
screen is tiled with the root window backgroimd tile randomly re-origined each 
interval minutes. Otherwise, the screens' state do not change^ and the screen 
saver is not activated. The screen saver is deactivated, and all screen states are 
restored at the next keyboard or pointer input or at the next call to 
XFoiceScreenSaver with mode ScieenSaverReset. 

If the server-dependent screen saver method supports periodic change, the inter- 
val argument serves as a hint about how long the change period should be, and 
zero hints that no periodic change should be nuide. Examples of ways to change 
the screen include scrambling the colormap periodically, moving an icon image 
around the screen periodically, or tiling the screen with the root window back- 
ground tile, randomly re-origined periodically. 

XSetScreenSaver can generate a BadValue error. 

If the specified mode is ScreenSaverActive and the screen saver currently is 
deactivated, XForceScreenSaver activates the screen saver even if the screen saver 
had been disabled with a timeout of zero. If the specified mode is ScreenSaver- 
Reset and the screen saver currently is enabled, XForceScreenSaver deactivates 
the screen saver if it was activated, and the activation timer is reset to its initial 
state (as if device input had been received). 

XFoiceScreenSaver can generate a BadValue error. 

The XActivateScreenSaver function activates the screen saver. 

The XResetScreenSaver function resets the screen saver. 

The XGetScreenSaver fimction gets the current screen saver values. 

DIAGNOSTICS 

BadValue Some numeric value falls outside the range of values accepted 
by the request. Unless a specific range is specified for an argu^ 
ment, the full range defined by the argtmient's type is accepted. 
Any argument defined as a set of alternatives can generate this 
error. 

SEE ALSO 

Xlib - C Language X Interface 
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NAME 

XSetSelectionOwner, XGetSelectionOwner, XConvertSelection - manipulate win- 
dow selection 

SYNTAX 

XSetSelectionOwner(ii^2!ay, selection, oxvner, time) 
Display * display) 
Atom selection; 
Window otvner; 
Time time; 

Window XGetSelectionOwner(^isp%, selection) 
Display *displa\f; 
Atom selection; 

XConvertSelection (iispZoy, selection, target, property, retjjuestor, time) 
Display ^display; 
Atom selection, target; 
Atom property; 
Window requestor; 
Time time; 

ARGUMENTS 



display 


Specifies the connection to the XWD^ server. 


owner 


Specifies the owner of the specified selection atom. You can 
pass a window or None. 


property 


Specifies the property name. You also can pass None. 


requestor 


Specifies the requestor. 


selection 


Specifies the selection atom. 


target 


Specifies the target atom. 


time 


Specifies the time. You can pass either a timestamp or Current- 
Time. 



DESCRIPTION 

The XSetSelectionOwner fimction changes the owner and last-change time for 
the specified selection and has no effect if the specified time is earlier than the 
current last-change time of the specified selection or is later than the current XwiN 
server time. Otherwise, the last-change time is set to the specified time, with 
CurrentTime replaced by the current server time. If the owner window is 
specified as None, then the owner of the selection becomes None (that is, no 
owner). Otherwise, the owner of the selection becomes the client executing the 
request. 

If the new owner (whether a client or None) is not the same as the current owner 
of the selection and the current owner is not None, the current owner is sent a 
SelectionClear event. If the client that is the owner of a selection is later ter- 
minated (that is, its connection is closed) or if the owner window it has specified 
in the request is later destroyed, the owner of the selection automatically reverts 
to None, but the last-change time is not affected. The selection atom is uninter- 
preted by the XwiN server. XGetSelectionOwner returns the owner window. 
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which is reported in SelectionRequest and SelectionClear events. Selections are 
global to the XwiN server. 

XSeiSelectionOwner can generate BadAtom and BadWindow errors. 

The XGetSelectionOwner function returns the window ID associated with the 
window that currently owns the specified selection. If no selection was specified, 
the function returns the constant None. If None is returned, there is no owner 
for the selection. 

XGetSelectionOwner can generate a BadAtom error. 

XConvertSelection requests that the specified selection be converted to the 
specified target type: 

• If the specified selection has an owner, the XwiN server sends a Selection- 
Request event to that owner. 

• If no owner for the specified selection exists, the XwiN server generates a 
SelectionNotify event to the requestor with property None. 

In either event, the arguments are passed on unchanged. There are two 
predefined selection atoms: PRIMARY and SECONDARY. 

XConvertSelection can generate BadAtom and BadWindow errors. 

DIAGNOSTICS 

BadAtom A value for an Atom argument does not name a defined Atom. 

BadWindow A value for a Window argument does not name a defined Win- 
dow. 

SEE ALSO 

Xlib - C Language X Interface 
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NAME 

XSetSizeHints, XGetSizeHints - set or get window size hints 
SYNTAX 

XSetSizeHints(it^2ay, w, hints, property) 
Display * display) 
Window w; 
XSizeHints */imte; 
Atom property; 

Status XGetSizeHints (flfjsp%, w, hints jeturn, property) 
Display *display; 
Window w; 

XSizeHints *hintsjetum', 
Atom property; 



ARGUMENTS 

display Specifies the connection to the XwiN server. 

hints Specifies a pointer to the size hints. 

hints jetum Returns the size hints. 

property Specifies the property name. 

w Specifies the window. 
DESCRIPTION 



The XSetSizeHints fimction sets the XSizeHints structure for the named pro- 
perty and the specified window. This is used by XSetNormalHints and XSet- 
ZoomHints, and can be used to set the value of any property of type 
WMjSIZE_HINTS. Thus, it may be useful if other properties of that type get 
defined. 

XSetSizeHints can generate BadAlloc, BadAtom, and BadWindow errors. 

XGetSizeHints returns the XSizeHints structure for the named property and the 
specified window. This is used by XGetNormalHints and XGetZoomHints. It 
also can be used to retrieve the value of any property of t5^e WM SIZE HINTS. 
Thus, it may be useful if other properties of that type get defined. XGet- 
SizeHints returns a nonzero status if a size hint was defined or zero otherwise. 

XGetSizeHints can generate BadAtom and BadWindow errors. 

DIAGNOSTICS 

BadAlloc The server failed to allocate the requested resoiu'ce or server 

memory. 

BadAtom A value for an Atom argument does not name a defined Atom. 

BadWindow A value for a Window argument does not name a defined Win- 
dow. 
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SEE ALSO 

XSetaassHintOXll), 

XSetCommandOXll), 

XSetIcx)nName(3Xll), 

XSetIconSizeHints(3Xll), 

XSetNormalHintsOXll), 

XSetStandardPropertiesOXll), 

XSetTransientForHintOXll), 

XSetWMHintsOXll), 

XSetZoomHintsOXll), 

XStoreName(3Xll) 

Xlib - C Language X Interface 
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NAME 

XSetStandardColormap, XGetStandardColonnap - set or get standard colormaps 
SYNTAX 

XSetStandardColormapC itsp2^, w, colormap, property) 
Display display; 
Window w; 

XStandardColormap *cobrmap; 

Atom property; /* RGB_BEST__MAP, etc. */ 

Status XGetStandardColormap( iisp/«y, w, colormap jeturn, property) 
Display ^display; 
Window w; 

XStandardColormap *colortnapjetum ; 
Atom property; /* RGB_BEST__MAP, etc. */ 

ARGUMENTS 

colormap Specifies the colormap. 

colormap j^um Returns the colormap associated with the specified atom. 
display Specifies the connection to the XwiN server. 

property Specifies the property name. 

w Specifies the window. 

DESCRIPTION 

The XSetStandardColonnap function usually is only used by window managers. 
To create a standard colormap, follow this procedure: 

1. Open a new connection to the same server. 

2. Grab the server. 

3. See if the property is on the property list of the root window for the screen. 

4. If the desired property is not present: 

• Create a colormap (not required for RGB_DEFAULT_MAP) 

• Determine the color capabilities of the display. 

• Call XAllocColorPlanes or XAllocColorCells to allocate cells in the 
colormap. 

• Call XStoreColors to store appropriate color values in the colormap. 

• Fill in the descriptive members in the XStandardColormap structure. 

• Attach the property to the root window. 

• Use XSetCloseDownMode to make the resource permanent. 

5. Ungrab the server. 

XSetStandardColonnap can generate BadAUoc, BadAtom, and BadWindow 
errors. 
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The XGetStandardColoniiap function returns the colormap definition associated 
with the atom supplied as the property argument. For example, to fetch the stan- 
dard Grayscale colormap for a display, you use XGetStandardColonnap with 
the following S3nitax: 

XGetStandardColormapCdpy, DefaultRootWindow(dpy), &cmap, XA_RGB_GRAY_^MAP); 

Once you have fetched a standard colormap, you can use it to convert RGB 
values into pixel values. For example, given an XStandardColonnap structure 
and floating-point RGB coefficients in the range 0.0 to 1.0, you can compose pixel 
values with the following C expression: 

pixel = base_pixel 

+ ((unsigned long) (0.5 + r * red^max)) * red^mult 

+ ((unsigned long) (0.5 + g * green max)) * green mult 

+ ((unsigned long) (0.5 + b * blue_max)) * blue mult; 

The use of addition rather than logical OR for composing pixel values permits 
allocations where the RGB value is not aligned to bit boundaries. 

XGetStandardColonnap can generate BadAtom and BadWindow errors. 



BadWindow A value for a Window argument does not name a defined Win- 



DIAGNOSTICS 

BadAlloc 



The server failed to allocate the requested resource or server 
memory. 

A value for an Atom argument does not name a defined Atom. 



BadAtom 



dow. 



SEE ALSO 



Xlib - C Language X Interface 
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NAME 

XSetStandardProperties - set standard window manager properties 
SYNTAX 

XSetStandardProperties (iispl^y, w, window jiame, iconjiame, iconjfixmap, argv, 
argc, hints) 
Display *display; 
Window w; 
char *windowjtame; 
char *iconjiame; 
Pixmap iconjnxmap; 
char '^argu; 
int argc; 

XSiz^ints *hints; 
ARGUMENTS 

argc Specifies the number of arguments. 

argp Specifies the application's argument list. 

display Specifies the connection to the XwiN server. 

hints Specifies a pointer to the size hints for the window in its normal 

state. 

iconjiame Specifies the icon name, which should be a null-terminated 

string. 

iconjnxmap Specifies the bitmap that is to be used for the icon or None. 
w Specifies the window. 

vnndowjiame Specifies the window name, which should be a null-terminated 
string. 

DESCRIPTION 

The XSetStandardProperties function provides a means by which simple applica- 
tions set the most essential properties with a single call. XSetStandardProperties 
should be used to give a window manager some information about your 
program's preferences. It should not be used by applications that need to com- 
municate more information than is possible with XSetStandardProperties. (Typi- 
cally, argv is the argv array of your main program.) 

XSetStandardProperties can generate BadAUoc and BadWindow errors. 

PROPERTIES 

WM^NAME, WMJCON NAME, WM^HINTS, WM__COMMAND, and 
WM_NORMALHINTS 

DIAGNOSTICS 

BadAUoc The server failed to allocate the requested resource or server 

memory. 

BadWindow A value for a Window argument does not name a defined Win- 
dow. 
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SEE ALSO 

XSetaassHintOXll), 

XSetCommandOXll), 

XSetlconNameOXll), 

XSetlconSizeHintsOXll), 

XSetNormalHintsOXll), 

XSetSizeHintsOXll), 

XSetTransientForHintOXll), 

XSetWMHintsOXll), 

XSetZoomHintsOXll), 

XStoreNameOXll) 

Xlib - C Language X Interface 
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NAME 

XSetState, XSetFunction, XSetPlanemask, XSetForeground, XSetBackgroimd - GC 
convenience routines 

SYNTAX 

XSetStSite(disphnf, gc, foreground, background, function, plane jnask) 
Display Vtsptoy; 
GCgc; 

unsigned long foreground, background; 
int function; 

unsigned long plane jnask; 

XSetFunction(i^is>pllay, gc, function) 
Display ^display; 
GCgc; 
int function; 

XSetPlaneMask(iispky, gc, plane jnask) 
Display *display; 
GCgc; 

unsigned long plane jnask; 

XSeiForeground(display, gc, foreground) 
Display *displajf; 
GCgc; 

unsigned long foreground; 

XSetBackground(display, gc, background) 
Display * display; 
GCgp; 

unsigned long background; 
ARGUMENTS 

background Specifies the background you want to set for the specified GC. 

display Specifies the connection to the XwiN server. 

foreground Specifies the foreground you want to set for the specified GC. 

function Specifies the function you want to set for the specified GC. 

gc Specifies the GC. 

plane jnask Specifies the plane mask. 
DESCRIPTION 

The XSetState function sets the foreground, background, plane mask, and fimc- 
tion components for the specified GC. 

XSetState can generate BadAUoc, BadGC, and BadValue errors. 
XSetFunctioii sets a specified value in the specified GC. 
XSetFunction can generate BadAlloc, BadGC, and BadValue errors. 
The XSetPlaneMask function sets the plane mask in the specified GC. 
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XSeiPlaneMask can generate BadAlloc and BadGC errors. 
The XSetForeground function sets the foreground in the specified GC. 
XSetFoieground can generate BadAlloc and BadGC errors. 
The XSetBackground function sets the background in the specified GC. 
XSetBackground can generate BadAlloc and BadGC errors. 
DIAGNOSTICS 

BadAlloc The server failed to allocate the requested resource or server 

memory. 

BadGC A value for a GContext argument does not name a defined 

GContext. 

BadValue Some ntmieric value falls outside the range of values accepted 
by the request. Unless a specific range is specified for an argu- 
ment, the full range defined by the argument's tj^e is accepted. 
Any argument defined as a set of alternatives can generate this 
error. 

SEE ALSO 

XCreateGCOXll), 

XQueryBestSizeOXll), 

XSetArcModeOXll), 

XSetQipOriginOXll), 

XSetFillStyleOXll), 

XSetFontOXll), 

XSetLineAttributesOXll), 

XSetTileOXll) 

Xlib - C Language X Interface 
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NAME 

XSetTile, XSetStipple, XSetTSOrigin - GC convience routines 

SYNTAX 

XS&tTile(display, gc, tile) 
Display *dispUy; 
GC gc; 
Pixmap tile; 

XSe^tippleidisplay, gc, stipple) 
Display ^display; 
GC gc; 

Pixmap stipple; 

XSetTSOrigin (ii^ky, gc, tsjcjmgin, ts_y_origin) 
Display * display; 
GCgc; 

int tsjcj)rigin, tsjfyrigin; 
ARGUMENTS 

display Specifies the connection to the XwiN server. 

gc Specifies the GC. 

stipple Specifies the stipple you want to set for the specified GC. 

tile Specifies the fill tile you want to set for the specified GC. 

tsj)cj)rigin 

tsj/j)rigin Specify the x and y coordinates of the tile and stipple origin. 

DESCRIPTION 

The XSetTile function sets the fill tile in the specified GC. The tile and GC must 
have the same depth, or a BadMatch error resiilts. 

XSetTile can generate BadAlloc, BadGC, BadMatch, and BadPixmap errors. 

The XSetStipple function sets the stipple in the specified GC. The stipple and 
GC must have the same depth, or a BadMatch error results. 

XSetStipple can generate BadAUoc, BadGC, BadMatch, and BadPixmap errors. 

The XSetTSOrigin function sets the tile/ stipple origin in the specified GC. When 
graphics requests call for tiling or stippling, the parent's origin will be interpreted 
relative to whatever destination drawable is specified in the graphics request. 

XSetTSOrigin can generate BadAlloc and BadGC errors. 

DIAGNOSTICS 

BadAUoc The server failed to allocate the requested resource or server 

memory. 

BadGC A value for a GContext argument does not name a defined 

GContext. 

BadMatch Some argument or pair of arguments has the correct type and 
range but fails to match in some other way required by the 
request. 
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BadPixmap A value for a Pixmap argument does not name a defined Fix- 
map. 

SEE ALSO 

XCrcateGC(3Xll), 

XQueryBest^e(3Xll), 

XSetAK:Mode(3Xll), 

XSetaipQrigin(3Xll), 

XSetFillStyle(3Xll), 

XSetFont(3Xll), 

XSetLineAttributes(3Xll), 

XSetState(3Xll) 

XHb - C Language X Interface 
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NAME 

XSetTransientForHint, XGetTransientForHint - set or get transient for hint 
SYNTAX 

XSetTransientForHint ((display, w, propjvindow) 
Display ^display; 
Window w; 
Window propjmndow; 

Status XGetTransientForHint (i/tsp/<iy, w, propjvindow_return) 
Display * display, 
Window w) 

Window *pTopjmndowjeturn; 
ARGUMENTS 

display Specifies the connection to the XwiN server. 

w Specifies the window. 

propjmndow Specifies the window that the WM_TRANSIENT_FOR property 
is to be set to. 

propjoindowjetum 

Returns the WM_TRANSIENT_FOR property of the specified 
window. 

DESCRIPTION 

The XSetTiansieittForHint function sets the WM TRANSIENT_FOR property of 
the specified window to the specified prop_window. 

XSetTransientForHint can generate BadAlloc and BadWindow errors. 

The XGetTransientForHint function returns the WM_TRANSIENT_FOR property 
for the specified window. 

XGetTransientForHint can generate a BadWindow error. 

PROPERTY 

WM_TRANSIENT_FOR 

DIAGNOSTICS 

BadAlloc The server failed to allocate the requested resource or server 
memory. 

BadWindow A value for a Window argument does not name a defined Window. 

SEE ALSO 

XSetClassHintOXll), 

XSetCommandOXll), 

XSetlconNameOXll), 

XSetlconSizeHintsOXll), 

XSetNormalHintsOXll), 

XSetSizeHints(3Xll), 

XSetStandardPropertiesOXll), 

XSetWMHintsOXll), 

XSetZoomHintsOXll), 

XStoreNameOXll) 

Xlib - C Language X Interface 
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NAME 

XSetWMHints, XGetWMHints ~ set or get window manager hints 
SYNTAX 

XSetWMHints (display, w, vmhints) 
Display *displajf; 
Window w; 
XWMHints *xvnihints; 

XWMHints »XGetWMHints(<iispZfly, w) 
Display ^display; 
Window w; 

ARGUMENTS 

display Specifies the connection to the XwiM server. 

w Specifies the window. 

lomhints Specifies a pointer to the window manager hints. 

DESCRIPTION 

The XSetWMHints function sets the window manager hints that include icon 
information and location, the initial state of the window, and whether the appli- 
cation relies on the window manager to get keyboard input. 

XSetWMHints can generate BadAlloc and BadWindow errors. 

The XGetWMHints function reads the window manager hints and returns NULL 
if no WM_HINTS property was set on the window or a pointer to a XWMHints 
structure if it succeeds. When finished with the data, free the space used for it by 
calling XFree. 

XGetWMHints can generate a BadWindow error. 

PROPERTY 

WM^HINTS 

DIAGNOSTICS 

BadAlloc The server failed to allocate the requested resource or server 

memory. 

BadWindow A value for a Window argument does not name a defined Win- 
dow. 

SEE ALSO 

XSetClassHintOXll), 

XSetCommandOXll), 

XSetlconNameOXll), 

XSetlconSizeHintsOXll), 

XSetNormalHintsOXll), 

XSetSizeHints(3Xll), 

XSetStandardPropertiesOXll), 

XSetTransientForHint(3Xll), 

XSetZoomHintsOXll), 

XStoreNameOXll) 

Xlib - C Language X Interface 
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NAME 

XSetZoomHints, XGetZoomHints - set or get zoom state hints 
SYNTAX 

XSet2jOomHints (ii^Iay, w, zhints) 
Display ^display; 
Window w; 
XSizeHints *Aints; 

Status XGetZbomHints(iz^20y, w, zhintsjetum) 
Display ^display; 
Window w; 

XSizeHints "^zhintsjetum; 
ARGUMENTS 

display Specifies the connection to the XwiN server. 

w Specifies the window. 

zhints Specifies a pointer to the zoom hints. 

zhintsjetum Returns the zoom hints. 
DESCRIPTION 

Many window managers think of windows in one of three states: iconic, normal, 
or zoomed. The XSetZoomHints function provides the window manager with 
information for the window in the zoomed state. 

XSetZoomHints can generate BadAlloc and BadWindow errors. 

The XGetZoomHints function returns the size hints for a window in its zoomed 
state. It returns a nonzero status if it succeeds or zero if the application specified 
no zoom size hints for this window. 

XGetZoomHints can generate a BadWindow error. 

PROPERTY 

WM^ZOOM_HINTS 

DIAGNOSTICS 

BadAlloc The server failed to allocate the requested resource or server 

memory. 

BadWindow A value for a Window argument does not name a defined Win- 
dow. 

SEE ALSO 

XSetClassHintOXll), 

XSetCommandOXll), 

XSetIconName(3Xll), 

XSetlconSizeHintsOXll), 

XSetNormalHintsOXll), 

XSetSizeHints(3Xll), 

XSetStandardPropertiesOXll), 

XSetTransientForHintOXll), 

XSetWMHintsOXll), 

XStoreName(3Xll) 

Xlib - C Language X Interface 
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NAME 

XStoreBytes, XStoreBuffer, XFetchBytes, XFetchBuffer, XRotateBiiffers - manipu- 
late cut and paste buffers 

SYNTAX 

XSioreBytesidisplo}/, bytes, nhytes) 
Display *display; 
char *bytes; 
int hbytes; 

XSioreBuiieT (display, bytes, nbytes, buffer) 
Display *di$play; 
char *bytes; 
int nbytes; 
int buffer; 

char *XFetchBytes ((iisp%, nbytesjreturn) 
Display *display; 
int *nbytesjetum; 

char *XFetchBuffer(iisp%, nbytes jetum, buffer) 
Display * display; 
int *nbytesjretum; 
int buffer; 

XRotateBuffers(<itspIfly, rotate) 
Display * display; 
int rotate; 

ARGUMENTS 

buffer Specifies the buffer in which you want to store the bytes or 

from which you want the stored data returned. 

bytes Specifies the bytes, which are not necessarily ASQI or null- 

terminated. 

display Specifies the connection to the XwiN server. 

nbytes Specifies the number of bytes to be stored. 

nbytesjreturn Returns the number of bytes in the buffer. 
rotate Specifies how much to rotate the cut buffers. 

DESCRIPTION 

Note that the cut buffer's contents need not be text, so zero bytes are not special. 
The cut buffer's contents can be retrieved later by any client calling XFetchBytes. 

XStoreBytes can generate a BadAlloc error. 

If the property for the buffer has never been created, a BadAtom error results. 

XStoreBuff er can generate BadAlloc and BadAtom errors. 

The XFetchBytes function returns the number of bytes in the nbytes_retum argu- 
ment, if the buffer contains data. Otherwise, the function returns NULL and sets 
nbytes to 0. The appropriate amount of storage is allocated and the pointer 
returned. The client must free this storage when finished with it by calling 
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XFrec. Note that the cut buffer does not necessarily contain text, so it may con- 
tain embedded zero bytes and may not terminate with a null byte. 

The XFetdiBuffer function returns zero to the nbytes_return argument if there is 
no data in the buffer. 

XFetdiBuffer can generate a BadValue error. 

The XRotateBuffers function rotates the cut buffers, such that buffer 0 becomes 
buffer n, buffer 1 becomes n + 1 mod 8, and so on. This cut buffer numbering is 
global to the display. Note that XRotateBuffers generates BadMatch errors if 
any of the eight buffers have not been created. 

XRotateBuffers can generate a BadMatch error. 

DIAGNOSTICS 

BadAlloc The server failed to allocate the requested resource or server 



memoiy. 



BadAtom 
BadMatch 



A value for an Atom argument does not name a defined Atom. 



Some argument or pair of arguments has the correct type and 
range but fails to match in some other way required by the 
request. 



BadValue 



Some nimieric value falls outside the range of values accepted 
by the request. Unless a specific range is specified for an argu- 
ment, the full range defined by the argument's type is accepted. 
Any argument defined as a set of alternatives can generate this 
error. 



SEE ALSO 



Xlib - C Language X Interface 
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NAME 

XStoreColors, XStoreG>lor, XStoreNamedColor - set colors 
SYNTAX 

XStoreColors (display, colomtap, color, ncolor$) 
Display *display; 
Colormap colomtap; 
XColor colorU; 
int ncolors; 

XStoreColor (display, colomtap, color) 
Display *display; 
Colormap colomtap; 
XColor *color; 

XStoreNamedColor ((display, colormap, color, pixel, flags) 
Display "^display; 
Colormap colomtap; 
char "^color; 
unskned long pixel; 
mi pigs; 

ARGUMENTS 



color 


Specifies the pixel and RGB values or the color name string (for 




example, red). 


color 


Specifies an array of color definition structures to be stored. 


colormap 


Specifies the colormap. 


display 


Specifies the connection to the XwiN server. 


flags 


Specifies which red, green, and blue components are set. 


ncolors 


Specifies the number of XColor structures in the color definition 




array. 


pixel 


Specifies the entry in the colormap. 



DESCRIPTION 

The XStoreColois function changes the colormap entries of the pixel values 
specified in the pixel members of the XColor structures. You specify which color 
components are to be changed by setting DoRed, DoGreen, and/or DoBlue in 
the flags member of the XColor structures. If the colormap is an installed map 
for its screen, the changes are visible immediately. XStoreColors changes the 
specified pixels if they are allocated writable in the colormap by any client, even 
if one or more pixels generates an error. If a specified pixel is not a valid index 
into the colormap, a BadValue error results. If a specified pixel either is unallo- 
cated or is allocated read-only, a BadAccess error results. If more than one pixel 
is in error, the one that gets reported is arbitrary. 

XStoreColors can generate BadAccess, BadColor, and BadValue errors. 

The XStoreColor function changes the colormap entry of the pixel value specified 
in the pixel member of the XColor structure. You specified this value in the pixel 
member of the XColor structure. This pixel value must be a read/write cell and 
a valid index into the colormap. If a specified pixel is not a valid index into the 



10/89 



Page 1 



XStoreColor8(3X11) 



XStoreColor8(3X11) 



colormap, a BadValue error results. XStoreColor also changes the red, green, 
and/or blue color components. You specify which color components are to be 
changed by setting DoRed, DoGreen, and/or DoBlue in the flags member of 
the XCoIor structure. If the colormap is an installed map for its screen, the 
changes are visible immediately. 

XStoreColor can generate BadAccess, BadColor, and BadValue errors. 

The XStoreNamedColor function looks up the named color with respect to the 
screen associated with the colormap and stores the result in the specified color- 
map. The pixel argument determines the entry in the colormap. Tlie flags argu- 
ment determines which of the red, green, and blue components are set. You can 
set this member to the bitwise inclusive OR of the bits DoRed, DoGreen, and 
DoBlue. If the specified pixel is not a valid index into the colormap, a BadValue 
error results. If the specified pixel either is unallocated or is allocated read-only, 
a BadAccess error results. You should use the ISO Latin-1 encoding; uppercase 
and lowercase do not matter. 

XStoreNamedColor can generate BadAccess, BadColor, BadName, and Bad- 
Value errors. 

DIAGNOSTICS 

BadAccess A client attempted to free a color map entry that it did not 
already allocate. 

BadAccess A client attempted to store into a read-only color map entry. 

BadColor A value for a Colormap argument does not name a defined 

Colormap. 

BadName A font or color of the specified name does not exist. 

BadValue Some nimieric value falls outside the range of values accepted 

by the request. Unless a specific range is specified for an argu- 
ment, the full range defined by the argimient's type is accepted. 
Any argument defined as a set of alternatives can generate this 
error. 

SEE ALSO 

XAllocColor(3Xll), 

XCreateColormapOXll), 

XQueryColorOXll) 

Xlib - C Language X Interface 



Page 2 



10/89 



XStoreName(3X11) 



XStoreNamd(3X11) 



NAME 

XStoreName, XFetchName - set or get window names 
SYNTAX 

XStoreNameidisplajf, w, mndowjiame) 
Display ^displey; 
Window w; 
char *zoindowjume; 

Status XFetchName((2ispi^, w, window jiamejeiurn) 
Display "^display; * ~ 

Window w) 

char **windowjiamejelum) 
ARGUMENTS 

display Specifies the connection to the XwiN server. 

w Specifies the window. 

mndowjume Specifies the window name, which should be a null-terminated 
string. 

vnndowjtamejreturn 

Returns a pointer to the window name, which is a null- 
terminated string. 

DESCRIPTION 

The XStoreName function assigns the name passed to window_name to the 
specified window. A window manager can display the window name in some 
prominent place, such as the title bar, to allow users to identify windows easily. 
Some window managers may display a window's name in the window's icon, 
although they are encouraged to use the window's icon name if one is provided 
by the application. 

XStoreName can generate BadAlloc and BadWindow errors. 

The XFetchName function returns the name of the specified window. If it 
succeeds, it returns nonzero; otherwise, if no name has been set for the window, 
it returns zero. If the WM_NAME property has not been set for this window, 
XFetchName sets window_name_return to NULL. When finished with it, a client 
must free the window name string using XFree. 

XFetchName can generate a BadWindow error. 

PROPERTY 

WM__NAME 

DIAGNOSTICS 

BadAlloc The server failed to allocate the requested resource or server 
memory. 

BadWindow A value for a Window argument does not name a defined Window. 
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SEE ALSO 

XSetCommandOXl 1), 

XSetIconName(3Xll), 

XSetlconSizeHintsOXl 1 ), 

XSetNonnalHints(3XllX 

XSetSizeHints(3Xll), 

XSetStandardPropertiesOXll), 

XSetWMHintsOXll), 

XSetZoomHintsOXll) 

Xlib - C Language X Interface 
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NAME 

XStringToKeysym, XKeys)miToString, XKeycodeToKeysym, XKeysymToKeycode 
- convert keysyms 

SYNTAX 

KeySym XStringToKeysym (sM'ng) 
char *stnng; 

char *XKejrs)anToString(fceysym) 
KeyS]^ Ixysym; 

KeyS3an XKeycodeToKeysym (display, keycode, index) 
Display ^display; 
Ke3<!!dde keycode; 
int index; 

Ke)K2ode XKeysymToKeycode(iisp/ay, keysym) 
Display * display; 
KeySym keysym; 



ARGUMENTS 




display 


Specifies the connection to the XwiN server. 


index 


Specifies the element of KejCode vector. 


keycode 


Specifies the KeyCode. 


keysym 


Specifies the YjsySym that is to be searched for or converted. 


string 


Specifies the name of the KeySym that is to be converted. 


DESCRIPTION 





Valid KeySym names are listed in <Xll/keys)rmdef Ji> by removing the XK_ 
prefix from each name. If the specified string does not match a valid KeySym, 
XStringToKeysym returns NoSymbol. 

The returned string is in a static area and must not be modified. If the specified 
KeySym is not defined, XKey8)anToString returns a NULL. 

The XKeycodeToKeysym function uses internal Xlib tables and returns the 
KeySym defined for the specified KeyCode and the element of the KeyCode vec- 
tor. If no sjonbol is defined, XKeycodeToKeysym returns NoSymbol. 

If the specified KeySjon is not defined for any KeyCode, XKeysymToKeycode 
returns zero. 

SEE ALSO 

XLookupKeysymOXll) 
Xlib - C Language X Interface 
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NAME 

XSynchronize, XSetAfterFunction - enable or disable s3atchronization 
SYNTAX 

int (*XSynchion\ze(display, onoff))0 
Oisplay ^display; 
Bool onoff; 

int (*XSetAfterFunction (iis^%^ procedure))0 
Display *display; 
int (*procedure)(y, 

ARGUMENTS 

display Specifies the connection to the XwiN server. 

procedure Specifies the function to be called after an Xlib function that 

generates a protocol request completes its work. 

on<^ Specifies a Boolean value that indicates whether to enable or 

disable synchronization. 

DESCRIPTION 

The XSynchronize function returns the previous after function. If onoff is True, 
XSjmchronize turns on synchronous behavior. If onoff is False, XSynchronize 
turns off synchronous behavior. 

The specified procedure is called with only a display pointer. XSetAfterFunction 
returns the previous after function. 

SEE ALSO 

XSetErrorHandlerOXll) 
XlUf - C Language X Interface 
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NAME 

XTextExtents, XTextExtentsl6, XQueryTextExtents, XQueryTextExtentsl6 - com- 
pute or query text extents 

SYNTAX 

XTextExtents (/oni^sifMct, string, nchars, direction jeiurn, font jiscentjeiurn, 
fontjiescent return, overaUjetum) 
XFontStruct '^fontjtruct; 
char *string; 
int nchars; 
int *directionjretum; 

int *fontjascentjeium, *f(mtjiescentjretum; 
XQvarStruct *overalljretumr 

XrextExkentsl6(font_struct, string, nchars, direction jretum, fontjiscentjetum, 
fontjdescentjetum, overalljetum) " " " 

XFontStruct */bnt sTrud; 
XCharZb *string;~ 
int nchars; 
int *direction jretum; 

int *f(mtjiscent_return, *f(mt_descentjreturn; 
XCharStruct *overaUjetum; 

XQueryTextExtents (display, /bnt_JD, string, nchars, directionjetum, 
font jtscent jretum, fontjiescentjetum, overalljretum) 
Display * display; 
XID font JD; 
char *string; 
int nchars; 
int *directianjretum; 

int *fontjtscent Jretum, *fontJkscentjeturn; 
XCharStruct *overalljetum; 

XQueryTexiExtentsl6idisplay,fontJD, string, nchars, directionjetum, 
fontjiscentjetum, fontjdescentjetum, overalljetum) 
Display ^display; 
XID font JD; 
XChar2b *string; 
int nchars; 
int ^directionjetum; 

int *fontjiscerUjeturn, *font_descentjeturn; 
XCharStruct *aoeralljetum; 

ARGUMENTS 

directionjetum Returns the value of the direction hint (FontLeftToRight or 
FontRightToLeft). 

display Specifies the connection to the XwiN server. 
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fontJD 



Specifies either the font ID or the GContext ID that contains the 
font. 



fontjiscentjretum 



Returns the font ascent. 



fontJUscentjretum 



Returns the font descent. 



font^struct 

nchars 

string 



Specifies a pointer to the XFontStnict structure. 
Specifies the number of characters in the character string. 
Specifies the character string. 



overalljretum Returns the overall size in the specified XCharStruct structure. 
DESCRIPTION 

The XTextExtents and XTextExtentsl6 functions perform the size computation 
locally and, thereby, avoid the round-trip overhead of XQueiyTextExtents and 
XQueiyTextExtent8l6. Both functions return an XQiarStruct structure, whose 
members are set to the values as follows. 

The ascent member is set to the maximum of the ascent metrics of all characters 
in the string. The descent member is set to the maximum of the descent metrics. 
The width member is set to the sum of the character-width metrics of all charac- 
ters in the string. For each character in the string, let W be the sum of the 
character-width metrics of all characters preceding it in the string. Let L be the 
left-side-bearing metric of the character plus W. Let R be the right-side-bearing 
metric of the character plus W. The Ibearing member is set to the minimum L of 
all characters in the string. The rbearing member is set to the maximum R. 

For fonts defined with linear indexing rather than 2-byte matrix indexing, each 
XChai2b structure is interpreted as a 16-bit number with bytel as the most- 
significant byte. If the font has no defined default character, undefined characters 
in the string are taken to have all zero metrics. 

The XQueiyTextExtents and XQueryTextExtentsl6 functions return the bound- 
ing box of the specified 8-bit and l^bit character string in the specified font or 
the font contained in the specified GC. These functions query the XwiN server 
and, therefore, suffer the round-trip overhead that is avoided by XTextExtents 
and XTextExtentsl6 . Both functions return a XCharStruct structure, whose 
members are set to the values as follows. 

The ascent member is set to the maximum of the ascent metrics of all characters 
in the string. The descent member is set to the maximum of the descent metrics. 
The width member is set to the sum of the character-width metrics of all charac- 
ters in the string. For each character in the string, let W be the sum of the 
character-width metrics of all characters preceding it in the string. Let L be the 
left-side-bearing metric of the character plus W. Let R be the right-side-bearing 
metric of the character plus W. The Ibearing member is set to the minimum L of 
all characters in the string. The rbearing member is set to the maximum R. 
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For fonts defined with linear indexing rather than 2-byte matrix indexing, each 
XChai2b structure is interpreted as a 16-bit number with bytel as the most- 
significant byte. If the font has no defined default character, undefined characters 
in the string are taken to have all zero metrics. 

XQueiyTextExtents and XQueryTextExtentslS can generate BadFont and 
BadGC errors. 

DIAGNOSTICS 

BadFont A value for a Font or GContext argument does not name a 

defined Font. 

BadGC A value for a GContext argument does not name a defined 

GContext. 

SEE ALSO 

XTextWidthOXll) 

Xlib - C Language X Interface 
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NAME 



XTextWidth, XTextWidthl6 - compute text width 



SYNTAX 



int XTextVfidth(f(mtjtruct, string, count) 
XFontStruct Jontjtruct; 
char *string; 
int count; 

int XTexiViidthl6Udnt_struct, string, count) 
XFontStruct *jfont_struct; 
XChar2b *string; 
int count; 



DESCRIPTION 

The XTextWidih and XTextWidthl6 functions return the width of the specified 
8-bit or 2-b5^e character strings. 

SEE ALSO 

XTextExtentsOXll) 

Xlib - C Language X Interface 
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ARGUMENTS 

count 

fontjtruct 
string 



Specifies the character count in the specified string. 
Specifies the font used for the width computation. 
Specifies the character string. 
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NAME 

XTranslateCoordinates - translate window coordinates 
SYNTAX 

Bool XTranslateCoordinates (display, srcjv, destjv, srcjx, src_y, destjcj'etum, 
destjfjeturn, child jetum) 
Display ^display; 
Window srcjv, destjv; 
int srcjc, srcjf; 

int *destjcjreturn, *de$t_y_retum ; 
Window *chiUjreturn; 



ARGUMENTS 



chiUjeium 


Returns the child if the coordinates are contained in a mapped 




child of the destination window. 


destjD 


Specifies the destination window. 


destjcjeturn 




destjfjeturn 


Return the x and y coordinates within the destination window. 


display 


Specifies the connection to the XwiN server. 


srcjp 


Specifies the source window. 


srcjc 




srcjf 


Specify the x and y coordinates within the source window. 


DESCRIPTION 





The XTranslateCoordinates function takes the src_x and srcjr coordinates rela- 
tive to the source window's origin and returns these coordinates to dest_x_return 
and dest_y_return relative to the destination window's origin. 



If XTranslateCoordinates returns zero, src_w and dest_w are on different 
screens, and dest_x_return and dest j^ retum are zero. If the coordinates are con- 
tained in a mapped child of dest w, that child is returned to child__return. Other- 
wise, child_return is set to None. 

XTranslateCoordinates can generate a BadWindow error. 
DIAGNOSTICS 

BadWindow A value for a Window argument does not name a defined Win- 
dow. 

SEE ALSO 

Xlib - C Language X Interface 
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NAME 

XrmUniqueQuark, XrmStringToQuark, XrmQuarkToString, XrmStringToQuark- 
List, XrmStringToBindingQiiarkList - manipulate resource quarks 

SYNTAX 

XrmQuark XrmUniqueQuarkO 

#define XrmStringToName(string) XrmStringToQuark(string) 
#de£ine XrmStringToClass(string) XnnStringToQuark(string) 
#define XrmStringToRepresentation(string) XrmStringToQuark(string) 

XrmQuark XrmStringToQuark(stnn^) 
char *string; 

#define XrmNameToString(name) XrmQuarkToString(name) 
#define XrmClassToString(class) XrmQuarkToString(class) 
#define XrmRepresentationToStringftype) XrmQuarkToString(type) 

char *XrmQuarkToString(<j«<irit) 
XrmQuark quark; 

#de£bie XrmStringToNameList(str, name) XrmStringToQuarkList((str), (name)) 
#define XrmStringToClassList(str,class) XrmStringToQuarkList((strX (class)) 

void XrmStringTo(2uarkList( sinwg, quarks jeturn) 
char *stnng; 

XrmCJuarkList quarksjetum) 

XrmStringToBindingQuarkList (s^rzwg, bindings _return, quarksjreturn) 
char *string; 

XrmBindingList bindings jetum; 
XrmQuarkList quarksjreturn', 

ARGUMENTS 

bindingsjetum Returns the binding list. 

quark Specifies the quark for which the equivalent string is desired. 

quarksjreturn Returns the list of quarks. 

string Specifies the string for which a quark is to be allocated. 

DESCRIPTION 

The XrmUniqueQuark function allocates a quark that is guaranteed not to 
represent any string that is known to the resource manager. 

These functions can be used to convert to and from quark representations. The 
string pointed to by the return value must not be modified or freed. If no string 
exists for that quark, XrmQuarkToString returns NULL. 

The XnnQuarkToString function converts the specified resource quark represen- 
tation back to a string. 

The XmiStringToQuarkList function converts the null-terminated string (gen- 
erally a fully qualified name) to a list of quarks. The components of the string 
are separated by a period or asterisk character. 
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A binding list is a list of type XimBindinglist and indicates if components of 
name or class lists are bound tightly or loosely (that is, if wildcarding of inter- 
mediate components is specified). 

t3rpedef enum {XrmBindTightly, XrmBindLoosely} XrmBinding, *XrmBindingList; 

XrmBindTightly indicates that a period separates the components, and 
XrmBindLoosely indicates that an asterisk separates the components. 

The XrmStiingToBindingQuarkList function converts the specified string to a 
binding list and a quark list. Component names in the list are separated by a 
period or an asterisk character. If the string does not start with period or aster- 
isk, a period is assumed. For example, "*a.b*c" becomes: 

quarks a b c 

bindings loose tight loose 

SEE ALSO 

XrmGetResource(3Xll), 
XrmInitialize(3Xll), 
XrmMergeDatabasesOXll), 
XrmPutResource(3Xll) 
Xlib - C Language X Interface 
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NAME 

XUnmap Window, XUnmapSubwindows - unmap windows 

SYNTAX 

XUnmapWindow(iisp/Iay, w) 
Display *dispUy; 
Window w; 

XUnmapSubwindows (i/ispky, w) 
Display *display; 
Window w; 

ARGUMENTS 

display Specifies the connection to the XwiN server. 

to Specifies the window. 

DESCRIPTION 

The XUnmapWindow function unmaps the specified window and causes the 
XwiN server to generate an UnmapNotify event. If the specified window is 
already unmapped, XUnmapWindow has no effect. Normal exposure processing 
on formerly obscured windows is performed. Any child window will no longer 
be visible imtil another map call is made on the parent. In other words, the 
subwindows are still mapped but are not visible until the parent is mapped. 
Unmapping a window will generate Expose events on windows that were form- 
erly obscured by it. 

XUnmapWindow can generate a BadWindow error. 

The XUnmapSubwindows function unmaps all subwindows for the specified 
window in bottom-to-top stacking order. It causes the XwiN server to generate 
an UnmapNotify event on each sub window and Expose events on formerly 
obscured windows. Using this function is much more efficient than unmapping 
multiple windows one at a time because the server needs to perform much of the 
work only once, for all of the windows, rather than for each window. 

XUnmapSubwindows can generate a BadWindow error. 

DIAGNOSTICS 

BadWindow A value for a Window argument does not name a defined Win- 
dow. 

SEE ALSO 

XChangeWindo wAttributesOXl 1), 

XConfigureWindow(3Xll), 

XCreateWindowOXll), 

XDestroyWindowOXll), 

XMapWindowOXll) 

XRaiseWindowOXll) 
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XWarpPointer (3X11 ) XWarpPointer (3X11 ) 



NAME 

XWarpPointer - move pointer 
SYNTAX 

XWarpPointer((iisplfly, srcjv, destjv, srcjc, srcjf, srcjvidth, srcjieight, destjc, 
desijf) 
Display * display; 
Window srcjv, destjv; 
int src x, srcj/; 

unsigned int srcjmdth, srcjieight ; 
int destjc, destjf; 

ARGUMENTS 

destjD 

destjc 
de^tji 

display 

srcjc 
srcjf 
srcjvidth 
srcjieight 

srcjv 

DESCRIPTION 

If dest_w is None, XWarpPointer moves the pointer by the offsets (dest_x, 
dest__y) relative to the current position of the pointer. If dest_w is a window, 
XWarpPointer moves the pointer to the offsets (dest_x, dest_y) relative to the ori- 
gin of dest_w. However, if src_w is a window, the move only takes place if the 
specified rectangle src_w contains the pointer. 

The src x and srcjyr coordinates are relative to the origin of src_w. If src_height 
is zero, it is replaced with the current height of src_w minus src^. If src_width 
is zero, it is replaced with the current width of src_w minus src_x. 

There is seldom any reason for calling this function. The pointer should normally 
be left to the user. If you do use this function, however, it generates events just 
as if the user had instantaneously moved the pointer from one position to 
another. Note that you cannot use XWaipPointer to move the pointer outside 
the confine_to window of an active pointer grab. An attempt to do so will only 
move the pointer as far as the closest edge of the confine_to window. 

XWarpPointer can generate a BadWindow error. 

DIAGNOSTICS 

BadWindow A value for a Window argument does not name a defined Win- 
dow. 

SEE ALSO 

XSetlnputFocusOXll) 
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Specifies the destination window or None. 

Specify the x and y coordinates within the destination window. 
Specifies the connection to the XwiN server. 

Specify a rectangle in the source window. 
Specifies the source window or None. 
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